J.J.'s Blogs

Python | OpenCV 專案：天堂私服遊戲輔助（四）目標優先序選擇

2026-04-22T01:00:00.000Z

⚠️ 免責聲明

本文章內容僅供學術研究與電腦視覺技術學習之用途，所有程式碼與技術說明均以教育目的為出發點。

本文作者不提供任何形式的輔助程式販售、散佈或商業服務。
本文所有範例程式僅限在自行架設的私有伺服器環境中測試，不得用於任何正式營運的線上遊戲伺服器。
使用遊戲輔助程式可能違反個別遊戲的使用者條款,並導致帳號封鎖、法律責任等後果，讀者須自行承擔一切相關風險與責任。
本文技術內容若被用於任何違法或損害他人利益之行為，作者概不負責。
私有伺服器的架設與使用涉及遊戲著作權相關法律問題，讀者應自行評估所在地區的法規，並確認於合法範圍內使用。

📚 前言

在上一篇 （三）YOLOv8 怪物偵測整合 中，我們完成了雙執行緒偵測架構，並做出 live（bbox）／ grid（扁平菱形小地圖） 兩種預覽模式，也支援執行中熱換模型。

本篇加入 目標優先序選擇：當畫面同時出現多隻怪物時，依使用者設定的優先類別順序與距離畫面中心的遠近，選出最值得攻擊的目標，並在 live 與 grid 兩種預覽中都以紅色特別標記。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

系列總覽：

篇次	主題
一	主程式 GUI 框架與 HP/MP 血量監控
二	自動補藥
三	YOLOv8 怪物偵測整合
本篇（四／最終篇）	目標優先序選擇

🎯 本篇目標

建立 target_selector.py：依「類別優先清單 + 距離畫面中心」排序，從偵測結果挑出最優先目標
微調 detector.py：render() / render_grid() 接收 target，讓 live 模式在鎖定目標框上畫紅色、grid 模式把鎖定格塗紅
main.py 更新：SharedState 新增 target 欄位；detection_loop 呼叫 TargetSelector.select() 後把結果餵進 render()
UI 新增「優先類別」輸入欄（逗號分隔），預覽區底部顯示當前鎖定目標；優先清單可執行中熱切換

🗂️ 本篇新增／更新檔案

lineage_assistant/
├── main.py                   ← 更新（SharedState + Thread 2 + UI + _poll 推送優先清單）
├── window_capture.py         ← 不變
├── hp_monitor.py             ← 不變
├── auto_potion.py            ← 不變
├── detector.py               ← 更新（render / render_grid 接收 target）
├── target_selector.py        ← 新增（本篇重點）
├── calibrate_game_roi.py     ← 不變
└── models/
    └── lineage_detector.pt

💻 目標優先序模組：target_selector.py

排序規則（由高到低）：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

類別在優先清單中的位置越靠前，優先度越高
未列入清單的類別排最後
同優先度時，距離畫面中心越近越優先（減少滑鼠移動距離）

Thread 2 每秒會跑幾次 select()，若目標每幀都寫 log 會洗版，所以這裡用 _last_key 只在「目標實際切換」時才寫一筆。

# target_selector.py
import math
from typing import Callable, Dict, List, Optional


class TargetSelector:
    def __init__(self,
                 priority_classes: Optional[List[str]] = None,
                 min_conf: float = 0.0,
                 log_fn: Optional[Callable[[str], None]] = None):
        # detector.conf 已先做過一道信心度過濾；這裡 min_conf 預設 0 不重複過濾，
        # 想只鎖定高信心目標時才拉高
        self.priority  = list(priority_classes or [])
        self.min_conf  = min_conf
        self._log      = log_fn or (lambda msg: None)
        self._last_key = None   # (name, center) — 只在目標切換時寫日誌

    def select(self, detections: List[Dict],
               frame_center: Optional[tuple] = None) -> Optional[Dict]:
        """從偵測結果中選出最優先目標；無可選目標則回傳 None"""
        valid = [d for d in detections if d["conf"] >= self.min_conf]
        if not valid:
            if self._last_key is not None:
                self._log("目標：無")
                self._last_key = None
            return None

        def sort_key(d):
            name = d["name"]
            try:
                prio = self.priority.index(name)
            except ValueError:
                prio = len(self.priority)     # 未列出的類別排最後
            dist = 0.0
            if frame_center:
                cx, cy = d["center"]
                dist = math.hypot(cx - frame_center[0], cy - frame_center[1])
            return (prio, dist)

        valid.sort(key=sort_key)
        target = valid[0]

        key = (target["name"], target["center"])
        if key != self._last_key:
            self._log(
                f"🎯 鎖定目標：{target['name']} "
                f"({target['conf']:.2f}) @ {target['center']}"
            )
            self._last_key = key
        return target

🔧 detector.py

Part 3 的 annotate() 本來就能接 target（鎖定的框畫紅色），只是 render() 派發器沒把它傳下去、render_grid() 也還沒用到。本篇補兩件事：

render() 加上 target 參數並派發下去
render_grid() 新增 target 參數，命中鎖定目標的那一格填紅色（其他怪物仍是黃色）

以下是完整的更新後 detector.py（imports 與模組常數 VIEW_EW / VIEW_NS / GRID_HALF / CANVAS_W / CANVAS_H / get_game_roi / get_tile_px 沿用 Part 3，改動處用 # ← 本篇新增 標註）：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# detector.py
from typing import Dict, List, Literal, Optional

import cv2
import numpy as np
from ultralytics import YOLO

from window_capture import (get_game_roi, get_tile_px,
                            TILES_PER_HALF_WIDTH, TILES_PER_HALF_HEIGHT)

# 菱形視野邊界（把螢幕上「左右 ±8 / 上下 ±10」換算回 iso 世界座標）
VIEW_EW    = 2 * TILES_PER_HALF_WIDTH    # 東西邊界：|wx + wy| ≤ 16
VIEW_NS    = 2 * TILES_PER_HALF_HEIGHT   # 南北邊界：|wy - wx| ≤ 20
GRID_HALF  = (VIEW_EW + VIEW_NS) // 2    # 迴圈迭代半徑（菱形 4 角 |wx|/|wy| 最大 = 18）

CANVAS_W   = 200                         # 小地圖畫布寬（視野寬 16·DW = 192，加一點邊距）
CANVAS_H   = 130                         # 小地圖畫布高（視野高 20·DH = 120，加一點邊距）


class Detector:
    def __init__(self, model_path: str, conf: float = 0.5):
        self.model   = YOLO(model_path)
        self.conf    = conf
        self.enabled = True
        self.mode: Literal["live", "grid"] = "live"

    def detect(self, frame) -> List[Dict]:
        """回傳偵測結果，每筆為：
        {"name": str, "conf": float,
         "box": (x1, y1, x2, y2), "center": (cx, cy)}
        """
        results = self.model(frame, conf=self.conf, verbose=False)
        detections = []
        for r in results:
            for box in r.boxes:
                name = self.model.names[int(box.cls)]
                c    = float(box.conf)
                x1, y1, x2, y2 = map(int, box.xyxy[0])
                cx, cy = (x1 + x2) // 2, (y1 + y2) // 2
                detections.append({
                    "name": name, "conf": c,
                    "box": (x1, y1, x2, y2), "center": (cx, cy)
                })
        return detections

    def render(self, frame, detections: List[Dict],
               target: Optional[Dict] = None):      # ← 本篇新增 target 參數
        """主執行緒呼叫入口：依 mode 派發到 annotate / render_grid，並把 target 傳下去"""
        if self.mode == "grid":
            return self.render_grid(frame, detections, target=target)   # ← 本篇新增
        return self.annotate(frame, detections, target=target)

    def annotate(self, frame, detections: List[Dict],
                 target: Optional[Dict] = None):
        """live 模式：在原畫面上繪製偵測框（鎖定目標畫紅色，其他畫綠色）"""
        out = frame.copy()
        for d in detections:
            x1, y1, x2, y2 = d["box"]
            color = (0, 0, 220) if (target and d is target) else (0, 220, 0)
            cv2.rectangle(out, (x1, y1), (x2, y2), color, 2)
            label = f"{d['name']} {d['conf']:.2f}"
            cv2.putText(out, label, (x1, y1 - 6),
                        cv2.FONT_HERSHEY_SIMPLEX, 0.5, color, 1)
        return out

    def render_grid(self, frame, detections: List[Dict],
                    target: Optional[Dict] = None):  # ← 本篇新增 target 參數
        """grid 模式：以扁平等角菱形格呈現怪物相對方位；鎖定目標格填紅"""
        fh, fw = frame.shape[:2]
        rx, ry, rw, rh = get_game_roi(fw, fh)
        px, py = rx + rw / 2, ry + rh / 2    # 玩家像素座標（ROI 中心）
        tw, th = get_tile_px(fw, fh)          # 一格地磚像素：roi_w/16, roi_h/20（分母不同！）

        # 偵測中心 → 世界格座標；同時記錄 target 落在哪一格（本篇新增）
        monsters    = set()
        target_cell = None                                      # ← 本篇新增
        for d in detections:
            cx, cy = d["center"]
            dx, dy = cx - px, cy - py
            wx = round(dx / tw - dy / th)
            wy = round(dx / tw + dy / th)
            if abs(wx + wy) <= VIEW_EW and abs(wy - wx) <= VIEW_NS:
                monsters.add((wx, wy))
                if target is not None and d is target:          # ← 本篇新增
                    target_cell = (wx, wy)

        canvas = np.full((CANVAS_H, CANVAS_W, 3), 26, dtype=np.uint8)
        ccx, ccy = CANVAS_W // 2, CANVAS_H // 2
        DW, DH   = 12, 6

        WHITE, BLACK  = (240, 240, 240), (16, 16, 16)
        YELLOW, EDGE  = (0, 220, 255), (95, 95, 115)
        RED           = (0, 0, 220)                             # ← 本篇新增：鎖定目標色

        def diamond(wx, wy, fill, edge):
            cx = ccx + (wx + wy) * DW / 2
            cy = ccy + (wy - wx) * DH / 2
            pts = np.array([
                [cx,          cy - DH / 2],
                [cx + DW / 2, cy         ],
                [cx,          cy + DH / 2],
                [cx - DW / 2, cy         ],
            ], dtype=np.int32)
            if fill is not None:
                cv2.fillConvexPoly(canvas, pts, fill)
            cv2.polylines(canvas, [pts], True, edge, 1, cv2.LINE_AA)

        for wx in range(-GRID_HALF, GRID_HALF + 1):
            for wy in range(-GRID_HALF, GRID_HALF + 1):
                if abs(wx + wy) > VIEW_EW: continue
                if abs(wy - wx) > VIEW_NS: continue
                if wx == 0 and wy == 0:
                    diamond(wx, wy, BLACK, WHITE)               # 玩家
                elif (wx, wy) == target_cell:                   # ← 本篇新增分支
                    diamond(wx, wy, RED, WHITE)                 #    鎖定目標：紅底 + 白邊
                elif (wx, wy) in monsters:
                    diamond(wx, wy, YELLOW, EDGE)               # 其他怪物
                else:
                    diamond(wx, wy, None, EDGE)                 # 空格
        return canvas

💻 執行緒架構（本篇）

相較 Part 3，差異只在 Thread 2 多繞一趟 TargetSelector.select()；Thread 1 與 Main 完全不變。

Worker Thread 1 (monitor_loop)                ← 不變
  └── capture_window → HPMonitor.read() → potion.check()
                     → frame_q.put_nowait(frame)

Worker Thread 2 (detection_loop)              ← 本篇更新
  └── frame_q.get() → detector.detect()
                    → selector.select(detections, frame_center)   ← 新增
                    → detector.render(frame, detections, target=target)
                    → SharedState.detections / target / preview

Main Thread (tkinter)
  └── root.after(200ms) → _poll → 更新 HP/MP + 預覽 + 當前目標 label
                                → 即時把優先清單推回 TargetSelector

💻 主程式：main.py（最終篇版本）

這段內容已加密

需要 ☕ 咖啡會員 或更高等級的密碼才能閱讀

💡 年度公開密碼，到 /support 直接取得

圖：整合目標優先序選擇的主程式，Thread 2 呼叫 TargetSelector 選出目標後以紅框標記，UI 顯示當前鎖定目標的名稱與信心度

⚠️ 注意事項

🎯 優先序與類別名稱

類別名稱要與訓練時完全一致：大小寫、底線要跟 data.yaml 或 classes.txt 對得上，拼錯只會變「未列出」落到最後。
未列入優先清單的類別仍會被偵測，只是排序時放最後；全部都沒列也 OK，這時會退化成「距離畫面中心近者優先」。
距離基準是畫面中心：若要改用角色實際位置（ROI 中心），把 selector.select() 的 frame_center 換成 get_game_roi 算出的中心即可。

🧵 與 Part 3 的熱切換共存

優先清單即時生效：_poll 每 200ms 從「優先類別」Entry 把字串解析成 list 寫回 selector.priority，執行中隨便改都下一幀生效，不用停啟。
min_conf 預設 0：detector.conf 已經先濾一次，這裡再濾一次會讓 UI 滑桿失去意義、目標也可能忽有忽無。想只鎖定很高信心的目標時才手動拉高。
熱換模型時 target 不會殘留：Thread 2 每輪都重算 target；detector.enabled=False 或模型未載入時會直接 state.update(target=None)，預覽的目標 label 會立刻回到「—」。

❓️ 新手常踩的雷

selector.priority = new_list 是整包換：字串解析的結果一次 assign，CPython 下是原子操作；不要用 .append() 累加，否則熱切換時會越加越長。
d is target 用 identity 判相等：annotate 與 render_grid 都用 d is target 判斷是否為鎖定目標，所以不能 deep-copy detections，否則紅框永遠畫不出來。
Entry 內容留空：_parse_priority 會回傳空 list，此時 TargetSelector 退化成純距離排序，不會崩潰。

🎯 結語

本篇也是整個天堂私服遊戲輔助系列的最終篇。 從 Part 1 的 tkinter GUI 與 HP/MP 血量偵測、Part 2 的 PostMessage 自動補藥、Part 3 的雙執行緒 YOLOv8 偵測整合，到本篇的目標優先序選擇，整套輔助程式的視覺辨識 → 狀態判讀 → 目標決策核心流程到這裡已經完整。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

至於更進一步的 自動攻擊怪物 與 自動撿取道具，因為涉及主動向遊戲下指令（攻擊熱鍵、滑鼠點擊），在法律與遊戲條款上相對敏感，本系列就不再實作。對有興趣延伸的讀者而言，前四篇打下的基礎已涵蓋核心技術 —— 鎖定後怎麼按下攻擊鍵、偵測到 item 類別後怎麼點擊，本質上都是把 SharedState.target / SharedState.detections 接到既有的 PostMessage 或滑鼠 API 上 —— 技術上不困難，是否實作與如何使用，請自行評估所在地區的法律與風險。

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
Ultralytics YOLOv8 官方文件
 Python math.hypot 文件
 Python queue.Queue 文件
 tkinter ttk.Combobox 文件‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Python | OpenCV 專案：天堂私服遊戲輔助（三）YOLOv8 怪物偵測整合

2026-04-21T01:00:00.000Z

⚠️ 免責聲明

本文章內容僅供學術研究與電腦視覺技術學習之用途，所有程式碼與技術說明均以教育目的為出發點。

本文作者不提供任何形式的輔助程式販售、散佈或商業服務。
本文所有範例程式僅限在自行架設的私有伺服器環境中測試，不得用於任何正式營運的線上遊戲伺服器。
使用遊戲輔助程式可能違反個別遊戲的使用者條款，並導致帳號封鎖、法律責任等後果，讀者須自行承擔一切相關風險與責任。
本文技術內容若被用於任何違法或損害他人利益之行為，作者概不負責。
私有伺服器的架設與使用涉及遊戲著作權相關法律問題，讀者應自行評估所在地區的法規，並確認於合法範圍內使用。

📚 前言

在上一篇 （二）自動補藥 中，我們完成了自動補藥功能，並透過 PostMessage 讓補藥熱鍵即使在背景也能送進目標視窗。

本篇加入 YOLOv8 怪物偵測，核心挑戰在於：YOLO 推論本身耗時，若直接塞進 Thread 1 會拖慢血量偵測的更新速率。解法是新增 Worker Thread 2 專門跑 YOLO，兩個執行緒透過 queue.Queue 溝通。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

系列總覽：

篇次	主題
一	主程式 GUI 框架與 HP/MP 血量監控
二	自動補藥
本篇（三）	YOLOv8 怪物偵測整合
四（最終篇）	目標優先序選擇

🎯 本篇目標

建立 detector.py：封裝 YOLOv8 推論，並提供 live（畫 bbox） 與 grid（扁平菱形小地圖） 兩種預覽模式
新增 Thread 2（detection_loop）專跑 YOLO，Thread 1 透過 frame_q = queue.Queue(maxsize=2) 丟舊幀給它，保證推論永遠跑最新畫面
UI 加入「怪物偵測設定」面板與即時預覽區塊，checkbox 與「🔄 載入模型」都可執行中熱切換
window_capture.py 內建 HUD_PCT_BY_SIZE 查表自動判定 ROI；附錄提供 calibrate_game_roi.py 讓你擴充新解析度

🗂️ 本篇新增檔案

lineage_assistant/
├── main.py                   ← 更新（怪物偵測設定面板 + 預覽切換 + Thread 2）
├── window_capture.py         ← 更新（加入 HUD_PCT_BY_SIZE 查表 / get_game_roi / get_tile_px）
├── hp_monitor.py             ← 不變
├── auto_potion.py            ← 不變
├── detector.py               ← 新增（本篇重點，含 live / grid 雙模式）
├── calibrate_game_roi.py     ← 附錄（要支援新解析度時才跑）
├── models/
│   └── lineage_detector.pt
└── config.json

🛠️ 套件安裝

1	pip install ultralytics pillow

pywin32、opencv-python、numpy 在前兩篇已安裝，不需要重複裝。

📁 模型檔案從哪來

本篇用到的 models/lineage_detector.pt，就是我們在 天堂私服 YOLOv8 物件偵測實戰 中一路從「私服截圖蒐集 → LabelImg 標記 → YOLOv8 訓練」產出的那顆 runs/detect/lineage_detector/weights/best.pt。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

只要把它複製或搬到專案的 models/ 目錄下即可：

1
2
3

lineage_assistant/
└── models/
    └── lineage_detector.pt   ← 從 runs/detect/lineage_detector/weights/best.pt 搬過來

若你還沒訓練過自己的模型，請先回去看上一篇把訓練流程跑完。也可以先拿 yolov8s.pt 官方預訓練權重接上來驗證整條管線通不通，只是偵測結果會是 COCO 類別（person、car…）而非怪物。

‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🗺️ 遊戲畫面 ROI 查表

天堂視窗並不是「拍到什麼都拿來算」：標題列、聊天框、小地圖、上方 HUD 這些區塊都不是真正的世界畫面，拿去推座標會錯。所以要把真正的遊戲畫面在整個視窗內的矩形切出來。

好消息是：Lineage 的內部解析度只有幾個固定選項（400×300、800×600、1200×900…），而且每種解析度配上相同的 Windows 標題列後，擷取到的視窗尺寸跟 HUD 佔比都是固定的。所以作法是：

作者私下用小工具對每種解析度量一次 HUD 佔比
把結果寫成查表常數放進 window_capture.py
程式啟動後依 capture_window 實際抓到的視窗大小查表，直接選對應 HUD_PCT

讀者不用自己校準 —— 除非你的遊戲解析度不在表內，才需要回去跑附錄的 calibrate_game_roi.py 補一筆。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

window_capture.py 新增常數與函式

# window_capture.py 底部新增（本篇新增）

# ── Lineage 各解析度的 HUD 佔比查表 ──
# key 是 capture_window 實際抓到的 (win_w, win_h)（含標題列與邊框）
# value 是該解析度下 HUD 在上/下/左/右四邊各佔視窗的比例
HUD_PCT_BY_SIZE = {
    (406, 329): { # 遊戲內 400×300
        "top": 0.079,
        "bottom": 0.185,
        "left": 0.002,
        "right": 0.000,
    },
    (802, 627): {  # 遊戲內 800×600
        "top":    0.080,
        "bottom": 0.220,
        "left":   0.000,
        "right":  0.000,
    },
    (1206, 929): { # 遊戲內 1200×900
        "top": 0.029,
        "bottom": 0.195,
        "left": 0.002,
        "right": 0.000,
    },
}

# 視野可視範圍：Lineage 實測螢幕寬能裝 ±8 tile-widths、螢幕高能裝 ±10 tile-heights
# 也就是 roi_w = 2·8·DW = 16·DW、roi_h = 2·10·DH = 20·DH（不是標準 iso 2:1 而是偏扁）
TILES_PER_HALF_WIDTH  = 8    # 水平可視半徑（格）
TILES_PER_HALF_HEIGHT = 10   # 垂直可視半徑（格）


def _pick_hud(win_w: int, win_h: int):
    """依視窗尺寸從查表挑 HUD_PCT；找不到精確匹配就回傳面積最接近的一筆"""
    if (win_w, win_h) in HUD_PCT_BY_SIZE:
        return HUD_PCT_BY_SIZE[(win_w, win_h)]
    target_area = win_w * win_h
    nearest = min(HUD_PCT_BY_SIZE.keys(),
                  key=lambda k: abs(k[0] * k[1] - target_area))
    return HUD_PCT_BY_SIZE[nearest]


def get_game_roi(win_w: int, win_h: int):
    """回傳 (x, y, w, h)：遊戲渲染畫面在整個視窗內的矩形"""
    hud = _pick_hud(win_w, win_h)
    t = int(win_h * hud["top"])
    b = int(win_h * hud["bottom"])
    l = int(win_w * hud["left"])
    r = int(win_w * hud["right"])
    return (l, t, win_w - l - r, win_h - t - b)


def get_tile_px(win_w: int, win_h: int):
    """回傳一格地磚在畫面上的像素尺寸 (tw, th)

    Lineage 視野是「左右 8 格、上下 10 格」的扁長方形，所以：
        DW = roi_w / 16（= 2·TILES_PER_HALF_WIDTH）
        DH = roi_h /  20（= 2·TILES_PER_HALF_HEIGHT）
    """
    _, _, rw, rh = get_game_roi(win_w, win_h)
    return (rw / (2 * TILES_PER_HALF_WIDTH),
            rh / (2 * TILES_PER_HALF_HEIGHT))

兩個 TILES_PER_HALF_* 是遊戲常數（不會因視窗大小而變）；換不同客戶端或視角縮放才需要改。

怎麼量 8 / 10？ 在遊戲裡把一個不動的地標（例如怪物或 NPC）放在人物正右方一格，往正左方走到地標剛好在畫面右邊界為止，走的格數 +1 就是水平半徑；垂直半徑同理（放正下方、往正上方走）。作者實測 Lineage 預設視角：水平 8、垂直 10。

附錄：新增解析度用的 calibrate_game_roi.py

HUD_PCT_BY_SIZE 沒涵蓋到你的解析度時才需要，流程：選取視窗 → 擷取一幀 → cv2.selectROI 框出「真正的遊戲畫面」→ 換算成四邊百分比印出來，複製一個 key-value 對貼進 HUD_PCT_BY_SIZE 就行。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

點此展開 calibrate_game_roi.py 完整程式碼

Python | OpenCV 專案：天堂私服遊戲輔助（二）自動補藥

2026-04-20T01:00:00.000Z

⚠️ 免責聲明

本文章內容僅供學術研究與電腦視覺技術學習之用途，所有程式碼與技術說明均以教育目的為出發點。

本文作者不提供任何形式的輔助程式販售、散佈或商業服務。
本文所有範例程式僅限在自行架設的私有伺服器環境中測試，不得用於任何正式營運的線上遊戲伺服器。
使用遊戲輔助程式可能違反個別遊戲的使用者條款，並導致帳號封鎖、法律責任等後果，讀者須自行承擔一切相關風險與責任。
本文技術內容若被用於任何違法或損害他人利益之行為，作者概不負責。
私有伺服器的架設與使用涉及遊戲著作權相關法律問題，讀者應自行評估所在地區的法規，並確認於合法範圍內使用。

📚 前言

在上一篇 （一）主程式 GUI 框架與 HP/MP 血量監控 中，我們建立了 tkinter 骨架，可以即時顯示 HP/MP 比例。

本篇加入 自動補藥 功能：當 HP 或 MP 低於設定閾值時，自動模擬按下補藥熱鍵，並新增設定面板讓使用者在 UI 上調整參數。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

系列總覽：

篇次	主題
一	主程式 GUI 框架與 HP/MP 血量監控
本篇（二）	自動補藥
三	YOLOv8 怪物偵測整合
四（最終篇）	目標優先序選擇

🎯 本篇目標

建立 auto_potion.py，封裝補藥邏輯與冷卻時間
用 PostMessage 把 WM_KEYDOWN / WM_KEYUP 直接送到目標視窗的 hwnd，背景也能按鍵（不搶焦點）
在 UI 新增：啟用開關、HP/MP 閾值滑桿、F5~F12 熱鍵下拉選單
Worker Thread 1 整合補藥邏輯，main.py 整體更新

🗂️ 本篇新增檔案

lineage_assistant/
├── main.py              ← 更新（加入補藥設定面板 + 傳入 AutoPotion）
├── window_capture.py    ← 不變
├── hp_monitor.py        ← 不變
├── auto_potion.py       ← 新增（本篇重點）
└── config.json

本篇沿用第一篇已安裝的 pywin32，不需要額外套件。

💻 自動補藥模組：auto_potion.py

設計重點：

check(hp, mp) 由 Worker Thread 1 呼叫，不能操作 tkinter 元件
使用 PostMessage 把 WM_KEYDOWN / WM_KEYUP 送到目標 hwnd，視窗可在背景；不像 pyautogui.press() 只會送到有焦點的視窗
使用 log_fn callback 把訊息傳回主執行緒的 log_q
cooldown 防止連按，避免瞬間消耗大量藥水

# auto_potion.py
import time
from typing import Callable, Optional

import win32api
import win32con


VK_MAP = {
    "f1":  win32con.VK_F1,  "f2":  win32con.VK_F2,
    "f3":  win32con.VK_F3,  "f4":  win32con.VK_F4,
    "f5":  win32con.VK_F5,  "f6":  win32con.VK_F6,
    "f7":  win32con.VK_F7,  "f8":  win32con.VK_F8,
    "f9":  win32con.VK_F9,  "f10": win32con.VK_F10,
    "f11": win32con.VK_F11, "f12": win32con.VK_F12,
}


def post_key(hwnd: int, key: str):
    """把 WM_KEYDOWN/UP PostMessage 到目標 hwnd，不需視窗在前景"""
    vk = VK_MAP.get(key.lower())
    if vk is None or not hwnd:
        return
    scan        = win32api.MapVirtualKey(vk, 0)
    lparam_down = (scan << 16) | 1
    lparam_up   = (scan << 16) | (1 | (1 << 30) | (1 << 31))
    win32api.PostMessage(hwnd, win32con.WM_KEYDOWN, vk, lparam_down)
    win32api.PostMessage(hwnd, win32con.WM_KEYUP,   vk, lparam_up)


class AutoPotion:
    def __init__(self,
                 hwnd: int,
                 hp_threshold: float = 0.6,
                 mp_threshold: float = 0.4,
                 hp_key: str = "f5",
                 mp_key: str = "f6",
                 cooldown: float = 1.5,
                 enabled: bool = True,
                 log_fn: Optional[Callable] = None):
        self.hwnd         = hwnd
        self.hp_threshold = hp_threshold
        self.mp_threshold = mp_threshold
        self.hp_key       = hp_key
        self.mp_key       = mp_key
        self.cooldown     = cooldown
        self.enabled      = enabled   # 可由主執行緒即時切換
        self._log         = log_fn or (lambda msg: None)
        self._last_hp_t   = 0.0
        self._last_mp_t   = 0.0

    def check(self, hp: float, mp: float):
        """根據當前 HP/MP 決定是否補藥"""
        if not self.enabled:
            return
        now = time.time()
        if hp < self.hp_threshold and (now - self._last_hp_t) >= self.cooldown:
            post_key(self.hwnd, self.hp_key)
            self._last_hp_t = now
            self._log(
                f"HP 補藥（{hp*100:.0f}% < {self.hp_threshold*100:.0f}%）"
                f"，按 [{self.hp_key.upper()}]"
            )
        if mp < self.mp_threshold and (now - self._last_mp_t) >= self.cooldown:
            post_key(self.hwnd, self.mp_key)
            self._last_mp_t = now
            self._log(
                f"MP 補藥（{mp*100:.0f}% < {self.mp_threshold*100:.0f}%）"
                f"，按 [{self.mp_key.upper()}]"
            )

💻 主程式：main.py（第二篇版本）

這段內容已加密

需要 ☕ 咖啡會員 或更高等級的密碼才能閱讀

💡 年度公開密碼，到 /support 直接取得

圖：整合自動補藥模組的完整主程式，UI 新增閾值滑桿與 F5~F12 熱鍵下拉選單，啟動時連同目標 hwnd 一起傳入 Worker Thread

⚠️ 注意事項

按鍵直接 PostMessage 到目標 hwnd：不搶焦點，你可以在別的視窗工作；按鍵只會進指定遊戲視窗。
DirectInput 遊戲可能不吃 PostMessage：本篇鎖定以 WM_KEYDOWN / WM_KEYUP 接收熱鍵的傳統 Win32 遊戲視窗（如天堂 L1J 系列私服）；若遊戲採 DirectInput/Raw Input，要改用 SendInput 並把視窗帶到前景才能生效。
冷卻時間 cooldown=1.5 秒：防止連按，依藥水生效速度調整。
面板設定皆為即時生效：checkbox、HP/MP 閾值滑桿、F5~F12 下拉選單都由 _poll 每 200ms 推進 AutoPotion，調了就馬上套用。
hwnd 例外，是啟動時一次讀取：切換目標視窗要先停止、重新 🎯 選取、再啟動。
執行緒不會再靜默死掉：monitor_loop 外層 try/except/finally 把 pywin32 例外吞進 log；_poll 偵測到執行緒掛掉會自動把 ▶ / ■ 按鈕切回「啟動」並提示看日誌。

🎯 結語

本篇的自動補藥功能是遊戲輔助的基礎，整個邏輯都在 Worker Thread 1 裡執行，與 UI 完全解耦。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

下一篇將加入 （三）YOLOv8 怪物偵測整合，新增 Worker Thread 2 專門負責 YOLO 推論，並在 UI 中嵌入即時偵測預覽視窗。

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
pywin32 GitHub
PostMessage - Win32 API
WM_KEYDOWN - Win32 API
tkinter ttk.Scale‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Python | OpenCV 專案：天堂私服遊戲輔助（一）主程式 GUI 框架與 HP/MP 血量監控

2026-04-19T01:00:00.000Z

⚠️ 免責聲明

本文章內容僅供學術研究與電腦視覺技術學習之用途，所有程式碼與技術說明均以教育目的為出發點。

本文作者不提供任何形式的輔助程式販售、散佈或商業服務。
本文所有範例程式僅限在自行架設的私有伺服器環境中測試，不得用於任何正式營運的線上遊戲伺服器。
使用遊戲輔助程式可能違反個別遊戲的使用者條款，並導致帳號封鎖、法律責任等後果，讀者須自行承擔一切相關風險與責任。
本文技術內容若被用於任何違法或損害他人利益之行為，作者概不負責。
私有伺服器的架設與使用涉及遊戲著作權相關法律問題，讀者應自行評估所在地區的法規，並確認於合法範圍內使用。

本系列的核心目的是展示 GUI 設計、多執行緒架構、螢幕擷取、影像分析 等電腦視覺技術的整合應用，相同技術同樣適用於工廠監控、遠端桌面分析等正當場景。

📚 前言

在上一篇 天堂私服 YOLOv8 物件偵測實戰 中，我們完成了 YOLOv8 怪物偵測模型的訓練與即時推論。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

這個系列（共 5 篇）將把訓練好的模型整合進一套完整的遊戲輔助程式，以逐步增加功能的方式帶你理解整個系統架構，每篇都附上可直接執行的完整 main.py。

系列總覽：

篇次	主題	重點功能
本篇（一）	主程式 GUI 框架與 HP/MP 血量監控	tkinter UI、螢幕擷取、血量偵測
二	自動補藥	閾值設定、熱鍵模擬、補藥邏輯
三	YOLOv8 怪物偵測整合	偵測執行緒、即時預覽視窗
四（最終篇）	目標優先序選擇	優先類別、距離排序、目標鎖定

🎯 本篇目標

建立 tkinter 暗色主題遊戲輔助視窗
實作「🎯 選取視窗」按鈕，讓使用者點擊即鎖定任一目標視窗（取得 hwnd、標題、PID）
用 pywin32 PrintWindow 擷取選定視窗畫面
用 HSV 色相範圍 + 最右側有色像素比例偵測 HP/MP 血量
在主程式內整合「⚙ 校準血條」按鈕，框選 HP / MP 血條位置
設計 SharedState + threading.Lock 的執行緒安全資料結構

🗂️ 本篇專案結構

lineage_assistant/
├── main.py              ← 主程式：UI、視窗選取、血條校準（本篇完成）
├── window_capture.py    ← 視窗擷取與滑鼠選窗模組（本篇完成）
├── hp_monitor.py        ← HP/MP 血量監控模組（本篇完成）
└── config.json          ← 由主程式「⚙ 校準血條」按鈕寫入

後續每篇會在同一目錄中新增模組，並更新 main.py。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🛠️ 套件安裝

1	pip install opencv-python pywin32

💡 pywin32 提供 win32gui、win32ui、win32api、win32process，用來呼叫 PrintWindow、WindowFromPoint、GetAsyncKeyState、GetWindowThreadProcessId 等 Windows API。若 import win32gui 失敗，補跑一次 post-install：
1
python -m pywin32_postinstall -install

💻 視窗擷取模組：window_capture.py

用 Windows PrintWindow API 擷取指定 hwnd 的視窗畫面，即使視窗被其他視窗遮擋也能拿到完整畫面（最小化除外）。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# window_capture.py
from ctypes import windll
import numpy as np
import win32gui
import win32process
import win32ui

GA_ROOT = 2   # GetAncestor flag：取頂層視窗

def window_from_point(x, y):
    """回傳 (x, y) 螢幕座標下的頂層視窗 (hwnd, title, pid)；找不到回傳 (None, '', 0)"""
    hwnd = win32gui.WindowFromPoint((x, y))
    if not hwnd:
        return None, "", 0
    hwnd = win32gui.GetAncestor(hwnd, GA_ROOT)
    _, pid = win32process.GetWindowThreadProcessId(hwnd)
    return hwnd, win32gui.GetWindowText(hwnd), pid

def capture_window(hwnd):
    """用 PrintWindow 擷取視窗畫面：被遮擋也能抓，最小化會拿到黑畫面"""
    left, top, right, bottom = win32gui.GetWindowRect(hwnd)
    w, h = right - left, bottom - top
    if w <= 0 or h <= 0:
        return None

    hwnd_dc  = win32gui.GetWindowDC(hwnd)
    mfc_dc   = win32ui.CreateDCFromHandle(hwnd_dc)
    save_dc  = mfc_dc.CreateCompatibleDC()
    save_bmp = win32ui.CreateBitmap()
    save_bmp.CreateCompatibleBitmap(mfc_dc, w, h)
    save_dc.SelectObject(save_bmp)

    # flag=2 (PW_RENDERFULLCONTENT)：支援 DWM 合成畫面，對多數現代應用必要
    result = windll.user32.PrintWindow(hwnd, save_dc.GetSafeHdc(), 2)
    img = np.frombuffer(save_bmp.GetBitmapBits(True), dtype=np.uint8).reshape((h, w, 4))

    win32gui.DeleteObject(save_bmp.GetHandle())
    save_dc.DeleteDC()
    mfc_dc.DeleteDC()
    win32gui.ReleaseDC(hwnd, hwnd_dc)

    return img[:, :, :3].copy() if result == 1 else None   # BGRA → BGR

💻 血量監控模組：hp_monitor.py

HPMonitor 透過 HSV 色彩比例 推算血條填充：

從畫面截出血條 ROI
轉換為 HSV 色彩空間
對目標色（HP 紅 / MP 藍）做閾值遮罩
找最右側有色像素欄位，除以總寬度得到填充比例（0.0 ~ 1.0）

HP / MP 兩組 ROI 各自儲存在 config.json，可用「⚙ 校準血條」按鈕隨時重新框選。

⚠️ HSV 的紅色色相橫跨 0 與 180 兩端，本範例只取 H=0~10 足以應付多數血條；若你的遊戲血條偏紫紅（H > 170），要同時 cv2.inRange 兩段再用 |（OR）合併成一張遮罩。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# hp_monitor.py
import cv2
import json
import numpy as np
import os

CONFIG_FILE    = "config.json"
DEFAULT_HP_ROI = (10, 10, 200, 20)
DEFAULT_MP_ROI = (10, 35, 200, 20)


class HPMonitor:
    def __init__(self):
        self.hp_roi = DEFAULT_HP_ROI
        self.mp_roi = DEFAULT_MP_ROI
        self._load_config()

    def _load_config(self):
        if not os.path.exists(CONFIG_FILE):
            return
        with open(CONFIG_FILE) as f:
            cfg = json.load(f)
        for key in ("hp_roi", "mp_roi"):
            if key in cfg:
                setattr(self, key, tuple(cfg[key]))

    def _color_ratio(self, frame, roi, lower, upper) -> float:
        """HSV 色相範圍遮罩 + 最右側有色像素欄 / 總寬度"""
        x, y, w, h = roi
        if w == 0 or h == 0:
            return 0.0
        hsv  = cv2.cvtColor(frame[y:y+h, x:x+w], cv2.COLOR_BGR2HSV)
        mask = cv2.inRange(hsv, np.array(lower), np.array(upper))
        cols = np.any(mask > 0, axis=0)
        if not np.any(cols):
            return 0.0
        return min(1.0, (int(np.max(np.where(cols))) + 1) / w)

    def read(self, frame):
        hp = self._color_ratio(frame, self.hp_roi,
                               [0, 100, 80], [10, 255, 255])
        mp = self._color_ratio(frame, self.mp_roi,
                               [100, 100, 80], [130, 255, 255])
        return hp, mp

💻 主程式：main.py

這段內容已加密

需要 ☕ 咖啡會員 或更高等級的密碼才能閱讀

💡 年度公開密碼，到 /support 直接取得

圖：主程式按下「🎯 選取視窗」後滑鼠變十字，點擊遊戲視窗即鎖定 hwnd / 標題 / PID；再按「⚙ 校準血條」彈出 OpenCV 視窗框選 HP、MP 血條後自動寫回 config.json

圖：以 tkinter 建立暗色主題輔助視窗，Worker Thread 即時擷取畫面並偵測 HP/MP，每 200ms 更新 UI 進度條與日誌

🚀 執行流程

1	python main.py

點 🎯 選取視窗 → 滑鼠變十字，點擊目標遊戲視窗即鎖定（hwnd、標題、PID）
點 ⚙ 校準血條 → 彈出 OpenCV 視窗，依序框選 HP 血條與 MP 魔力條（Enter 確認 / C 重選）
點 ▶ 啟動 → HP/MP 以 5fps 即時更新

下次啟動會自動讀取 config.json 裡已儲存的 ROI，不用重新校準。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

⚠️ 常見問題

血條偵測不準確：再按一次 ⚙ 校準血條 重新框選，範圍要涵蓋整條血條但不超出 UI 邊框。
HP 一直顯示 0%：調整 hp_monitor.py 的 H（色相）範圍，不同遊戲血條的紅 / 藍色調差異頗大。
按 🎯 選取視窗後點到錯的子視窗：程式已用 GetAncestor(GA_ROOT) 自動取頂層，若仍不正確就再按一次重選。
按 🎯 選取視窗沒反應：本功能用 GetAsyncKeyState 輪詢全域滑鼠，若被其他程式攔截（例如部分遠端桌面），改用滑鼠直接點實體視窗。
畫面是黑的：視窗被最小化時 Windows 不 render 畫面，PrintWindow 拿不到內容；把視窗從工作列還原即可。

🎯 結語

本篇建立了整個系列的骨架：tkinter 暗色 UI、SharedState 執行緒安全架構、pywin32 視窗擷取，以及用 HSV 色彩比例偵測 HP/MP 的血量監控模組。

下一篇將加入 （二）自動補藥 功能，當 HP 或 MP 低於設定閾值時自動按下補藥熱鍵，並為 UI 增加閾值與熱鍵設定面板。

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

註：以上參考了
pywin32 GitHub
tkinter 官方文件
 WindowFromPoint - Win32 API
GetAsyncKeyState - Win32 API

Python | OpenCV 專案：天堂私服 YOLOv8 物件偵測實戰

2026-04-18T01:00:00.000Z

⚠️ 免責聲明

本文章內容僅供學術研究與電腦視覺技術學習之用途，所有程式碼與技術說明均以教育目的為出發點，用於探討資料蒐集、影像標記、YOLOv8 模型訓練與即時物件偵測等技術在實際場景中的應用方式。

本文作者不提供任何形式的輔助程式販售、散佈或商業服務。
本文所有範例程式僅限在自行架設的私有伺服器環境中測試，不得用於任何正式營運的線上遊戲伺服器。
使用遊戲輔助程式可能違反個別遊戲的使用者條款，並導致帳號封鎖、法律責任等後果，讀者須自行承擔一切相關風險與責任。
本文技術內容若被用於任何違法或損害他人利益之行為，作者概不負責。
私有伺服器的架設與使用涉及遊戲著作權相關法律問題，讀者應自行評估所在地區的法規，並確認於合法範圍內使用。

本文的核心目的是展示 資料蒐集 → 標記 → YOLOv8 訓練 → 即時偵測 這套完整流程，私服環境僅作為一個可控、高效的資料來源範例。相同的流程同樣適用於工廠瑕疵偵測、倉儲物件辨識、醫療影像分析等正當場景。

📚 前言

在上一篇 MediaPipe 手勢控制應用 中，我們完成了手勢辨識的互動應用。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

這一篇是一個真實的遊戲輔助開發實戰：天堂私服 YOLOv8 物件偵測。

天堂私服的最大優勢是你能完全掌控遊戲環境：可以任意召喚怪物、調整地圖、控制光線與場景，讓資料蒐集變得極為高效。這個流程可以套用到任何你想偵測的遊戲物件。

🎯 專案目標

用私服環境快速蒐集遊戲截圖資料集
使用 LabelImg 標記怪物、NPC、道具等物件
以 YOLOv8 訓練自訂偵測模型
即時擷取遊戲畫面並進行物件偵測

🛠️ 套件安裝

1 2	pip install ultralytics pygetwindow pywin32 pip install labelImg # 標記工具

💡 pywin32 提供 win32gui、win32ui，用來呼叫 Windows PrintWindow API 擷取被遮擋的遊戲畫面。若 import win32gui 報錯，補跑一次 post-install：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌
1
python -m pywin32_postinstall -install
最小化時 Windows 不會 render 畫面，仍無法擷取。

🧰 共用工具：視窗擷取模組

擷取視窗畫面的邏輯，蒐集與偵測兩個步驟都會用到，抽出來共用。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# window_capture.py
from ctypes import windll
import numpy as np
import pygetwindow as gw
import win32gui
import win32ui

def find_game_window(title_keyword):
    """回傳符合標題關鍵字、可見、未最小化的視窗；找不到回傳 None"""
    for w in gw.getAllWindows():
        if (title_keyword.lower() in w.title.lower()
                and w.visible and not w.isMinimized
                and w.width > 0 and w.height > 0):
            return w
    return None

def list_visible_windows():
    """列出所有可見且有標題的視窗，方便診斷"""
    return [w.title for w in gw.getAllWindows() if w.title.strip() and w.visible]

def capture_window(hwnd):
    """用 PrintWindow 擷取視窗畫面：被遮擋也能抓，最小化會拿到黑畫面"""
    left, top, right, bottom = win32gui.GetWindowRect(hwnd)
    w, h = right - left, bottom - top
    if w <= 0 or h <= 0:
        return None

    hwnd_dc  = win32gui.GetWindowDC(hwnd)
    mfc_dc   = win32ui.CreateDCFromHandle(hwnd_dc)
    save_dc  = mfc_dc.CreateCompatibleDC()
    save_bmp = win32ui.CreateBitmap()
    save_bmp.CreateCompatibleBitmap(mfc_dc, w, h)
    save_dc.SelectObject(save_bmp)

    # flag=2 (PW_RENDERFULLCONTENT)：支援 DWM 合成畫面，對多數現代應用必要
    result = windll.user32.PrintWindow(hwnd, save_dc.GetSafeHdc(), 2)
    img = np.frombuffer(save_bmp.GetBitmapBits(True), dtype=np.uint8).reshape((h, w, 4))

    win32gui.DeleteObject(save_bmp.GetHandle())
    save_dc.DeleteDC()
    mfc_dc.DeleteDC()
    win32gui.ReleaseDC(hwnd, hwnd_dc)

    return img[:, :, :3].copy() if result == 1 else None   # BGRA → BGR

💻 步驟一：自動蒐集遊戲截圖

在私服中固定地點、怪物附近定時截圖，快速建立訓練資料集。

# collect_screenshots.py
import cv2
import os
import time
from window_capture import find_game_window, capture_window

SAVE_DIR     = "dataset/raw_images"
INTERVAL     = 0.5          # 每隔 0.5 秒截一張
TARGET       = 500          # 目標張數
WINDOW_TITLE = "Lineage"    # 遊戲視窗標題（部分符合即可）

os.makedirs(SAVE_DIR, exist_ok=True)

game_win = find_game_window(WINDOW_TITLE)
if game_win is None:
    print(f"找不到『{WINDOW_TITLE}』視窗，請先開啟遊戲")
    exit()

print(f"開始蒐集，目標 {TARGET} 張，間隔 {INTERVAL} 秒（Ctrl+C 停止）")

count = 0
while count < TARGET:
    frame = capture_window(game_win._hWnd)
    if frame is None:
        time.sleep(INTERVAL)
        continue

    cv2.imwrite(f"{SAVE_DIR}/{count:05d}.jpg", frame)
    count += 1
    if count % 50 == 0:
        print(f"已蒐集：{count}/{TARGET}")
    time.sleep(INTERVAL)

print(f"完成！共 {count} 張，儲存於 {SAVE_DIR}")

💡 私服蒐集技巧：
在同一張地圖、同一區域定點蒐集，減少背景多樣性帶來的干擾
不同時間段（白天/夜間）各蒐集一批，讓模型適應光線變化
如果要偵測多種怪物，分別在各怪物出沒的地圖蒐集

💻 步驟二：LabelImg 標記

1 2	# 安裝後直接執行 labelImg

標記流程：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Open Dir → 選擇 dataset/raw_images/
Change Save Dir → 選擇 dataset/raw_labels/
左側切換格式為 YOLO
按 W 畫框 → 輸入類別名稱（如 orc、troll、item）
按 Ctrl+S 儲存，D 切換下一張
開啟 Auto Save 可省略手動存檔

建議標記的類別（依需求調整）：

怪物類：orc, troll, dark_elf, zombie, ...
NPC 類：npc_shop, npc_quest, ...
道具類：item_weapon, item_armor, item_misc
角色類：player, other_player

💡 先只標記 1~2 個最重要的類別，訓練成功後再擴充。類別越少，模型越好訓練。

💻 步驟三：分割資料集

將原始截圖與標籤按 8:2 比例隨機分割為訓練集與驗證集，建立對應目錄結構。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# split_dataset.py
import os
import shutil
import random

SRC_IMAGES = "dataset/raw_images"
SRC_LABELS = "dataset/raw_labels"
DST_ROOT   = "dataset"
VAL_RATIO  = 0.2
random.seed(42)

for split in ["train", "val"]:
    os.makedirs(f"{DST_ROOT}/images/{split}", exist_ok=True)
    os.makedirs(f"{DST_ROOT}/labels/{split}", exist_ok=True)

files = [f for f in os.listdir(SRC_IMAGES)
         if f.lower().endswith((".jpg", ".png"))]
random.shuffle(files)

val_set = set(files[:int(len(files) * VAL_RATIO)])

for fname in files:
    split = "val" if fname in val_set else "train"
    stem  = os.path.splitext(fname)[0]

    shutil.copy(f"{SRC_IMAGES}/{fname}",
                f"{DST_ROOT}/images/{split}/{fname}")

    lbl = f"{SRC_LABELS}/{stem}.txt"
    if os.path.exists(lbl):
        shutil.copy(lbl, f"{DST_ROOT}/labels/{split}/{stem}.txt")
    else:
        open(f"{DST_ROOT}/labels/{split}/{stem}.txt", "w").close()

print(f"train: {len(files)-len(val_set)}, val: {len(val_set)}")

💻 步驟四：建立 data.yaml

從 LabelImg 產生的 classes.txt 自動讀取類別，生成 YOLOv8 訓練所需的 data.yaml 設定檔。

# create_yaml.py
import os

# 從 LabelImg 產生的 classes.txt 讀取類別
with open("dataset/raw_labels/classes.txt") as f:
    classes = [line.strip() for line in f if line.strip()]

yaml_content = f"""path: ./dataset
train: images/train
val:   images/val

nc: {len(classes)}
names:
"""
for i, cls in enumerate(classes):
    yaml_content += f"  {i}: {cls}\n"

with open("data.yaml", "w") as f:
    f.write(yaml_content)

print("data.yaml 已產生：")
print(yaml_content)

💻 步驟五：訓練 YOLOv8

以 YOLOv8s 預訓練模型為基礎，對遊戲截圖資料集進行訓練並輸出最佳偵測模型。

# train.py
from ultralytics import YOLO
import torch

print(f"GPU：{'可用 - ' + torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU'}")

model = YOLO("yolov8s.pt")

model.train(
    data="data.yaml",
    epochs=100,
    imgsz=640,
    batch=16,
    device=0 if torch.cuda.is_available() else "cpu",
    workers=0,          # Windows 必設 0
    patience=20,
    name="lineage_detector",
    plots=True,
)

print(f"\n訓練完成！best.pt：{model.trainer.best}")

💻 步驟六：即時遊戲畫面偵測

這段內容已加密

需要 ☕ 咖啡會員 或更高等級的密碼才能閱讀

💡 年度公開密碼，到 /support 直接取得

圖：開啟遊戲視窗截圖並以 YOLOv8 即時推論，在單一顯示視窗內用綠色框線標注所有偵測到的物件與信心度‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

⚠️ 注意事項

私服的優勢：可用 GM 指令隨時生怪、清場、調時間，蒐集成本極低。
解析度要一致：訓練與推論的視窗尺寸盡量固定，否則讓 imgsz 涵蓋所有情境。
標記品質 > 數量：500 張精標遠勝 2000 張草率標。
視窗不能最小化：改用 PrintWindow 後被其他視窗「遮擋」也能擷取，但最小化時 Windows 根本不 render 畫面，仍會拿到黑畫面；程式偵測到最小化會自動結束。
訓練路徑自動找：不同 Ultralytics 版本的 best.pt 位置會跑掉，程式已用 rglob 抓最新。
顯示用手動 cv2，不要 results[0].plot()：部分版本的 plot() 會另開視窗，畫在原 frame 上最可控。

📊 進階應用方向

自動攻擊：偵測到怪物後，取邊界框中心座標，用 pyautogui 點擊
自動撿取道具：偵測 item 類別，自動移動到物品位置按撿取
血量監控：偵測 HP 條區域，用 OCR 或色彩分析判斷血量百分比

🎯 結語

從私服蒐集資料、LabelImg 標記、YOLOv8 訓練到即時偵測，整套流程一天內就能跑完；換成其他遊戲或模擬器，步驟完全一樣。

下一篇進入 天堂私服遊戲輔助（一）主程式 GUI 框架與 HP/MP 血量監控，把訓練好的模型整合進一套有 GUI 的完整輔助程式。

註：以上參考了
Ultralytics YOLOv8 官方文件
 LabelImg GitHub
pygetwindow GitHub
pywin32 GitHub

Python | OpenCV 專案：MediaPipe 手勢控制應用

2026-04-17T01:00:00.000Z

📚 前言

在上一篇 小型圖片分類專案 中，我們完成了端對端的圖片分類系統。

這一篇介紹 MediaPipe 手勢控制應用。MediaPipe 是 Google 開發的跨平台機器學習管線框架，其中的 Hands 模組可以即時偵測手部的 21 個關鍵點，不需要 GPU，精度遠高於傳統輪廓法。

🎯 專案目標

使用 MediaPipe Hands 偵測手部關鍵點
實作手指計數（0 ~ 5）
自訂手勢辨識（OK、Rock、拳頭等）
整合互動應用：手勢控制螢幕畫筆

🛠️ 套件安裝

1	pip install mediapipe

🔎 MediaPipe Hands 關鍵點說明

MediaPipe Hands 會回傳手部 21 個關鍵點（Landmark），每個點有 x、y（相對比例）與 z（深度）：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

    8   12  16  20
    |   |   |   |
    7   11  15  19
4   6   10  14  18
|   5   9   13  17
3   |
2   0（手腕）
|
1

關鍵點	位置
0	手腕
1~4	大拇指（4 = 指尖）
5~8	食指（8 = 指尖）
9~12	中指（12 = 指尖）
13~16	無名指（16 = 指尖）
17~20	小指（20 = 指尖）

💻 基本手部偵測

使用 MediaPipe Hands 偵測手部 21 個關鍵點，即時繪製骨架連線並顯示於攝影機畫面

# detect_hands.py
import cv2
import mediapipe as mp

mp_hands   = mp.solutions.hands
mp_drawing = mp.solutions.drawing_utils

hands = mp_hands.Hands(
    static_image_mode=False,
    max_num_hands=2,
    min_detection_confidence=0.7,
    min_tracking_confidence=0.5,
)

cap = cv2.VideoCapture(0)
print("MediaPipe 手部偵測，按 q 離開")

while True:
    ret, frame = cap.read()
    if not ret:
        break

    frame = cv2.flip(frame, 1)   # 水平翻轉，讓畫面如鏡子
    rgb   = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
    result = hands.process(rgb)

    if result.multi_hand_landmarks:
        for hand_lm in result.multi_hand_landmarks:
            # 繪製 21 個關鍵點與連線
            mp_drawing.draw_landmarks(
                frame, hand_lm, mp_hands.HAND_CONNECTIONS
            )

    cv2.imshow("Hands", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

💻 手指計數

比較各手指指尖與第二關節的座標判斷每根手指是否伸直，回傳伸出的手指數量

# demo_count_fingers.py
def count_fingers(hand_lm, handedness):
    """
    回傳伸出的手指數量（0~5）
    handedness: "Left" 或 "Right"（MediaPipe 回傳的是鏡像後的手）
    """
    lm = hand_lm.landmark

    # 指尖與第二關節的 ID
    tip_ids  = [4, 8, 12, 16, 20]
    pip_ids  = [3, 6, 10, 14, 18]

    fingers = 0

    # 大拇指：比較 x 軸（左右手方向不同）
    if handedness == "Right":
        if lm[tip_ids[0]].x < lm[pip_ids[0]].x:
            fingers += 1
    else:
        if lm[tip_ids[0]].x > lm[pip_ids[0]].x:
            fingers += 1

    # 其他四指：比較 y 軸（指尖 y < 第二關節 y 表示伸直）
    for i in range(1, 5):
        if lm[tip_ids[i]].y < lm[pip_ids[i]].y:
            fingers += 1

    return fingers

💻 手勢辨識

根據關鍵點幾何關係辨識拳頭、讚、剪刀、OK、五指張開等特定手勢並回傳對應名稱‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# demo_recognize_gesture.py
def recognize_gesture(hand_lm):
    """辨識特定手勢，回傳手勢名稱"""
    lm = hand_lm.landmark

    tip_ids = [4, 8, 12, 16, 20]
    pip_ids = [3, 6, 10, 14, 18]

    # 各手指是否伸直
    fingers = [lm[tip_ids[i]].y < lm[pip_ids[i]].y for i in range(1, 5)]
    # 大拇指（簡化：只看是否向側邊伸出）
    thumb_open = abs(lm[4].x - lm[3].x) > 0.04

    # 拳頭：所有手指收起
    if not any(fingers) and not thumb_open:
        return "✊ 拳頭"

    # 讚：只有大拇指伸出，其他收起
    if thumb_open and not any(fingers):
        return "👍 讚"

    # 剪刀：食指與中指伸出
    if fingers[0] and fingers[1] and not fingers[2] and not fingers[3]:
        return "✌️ 剪刀"

    # OK：食指與大拇指靠近（其他手指伸出）
    dist = ((lm[4].x - lm[8].x)**2 + (lm[4].y - lm[8].y)**2) ** 0.5
    if dist < 0.06 and fingers[1] and fingers[2] and fingers[3]:
        return "👌 OK"

    # 五指全開
    if all(fingers) and thumb_open:
        return "🖐️ 五指張開"

    return ""

💻 完整互動應用：手勢畫筆

伸出食指時在畫布上繪製軌跡，握拳時清除畫布，將手勢繪圖疊加在攝影機畫面上顯示

用手勢控制螢幕畫筆，食指繪圖、拳頭清除畫布：

# gesture_painter.py
import cv2
import mediapipe as mp
import numpy as np

mp_hands   = mp.solutions.hands
mp_drawing = mp.solutions.drawing_utils

hands  = mp_hands.Hands(max_num_hands=1,
                         min_detection_confidence=0.7,
                         min_tracking_confidence=0.5)
cap    = cv2.VideoCapture(0)
canvas = None
prev_x, prev_y = None, None
color  = (0, 255, 0)

print("食指繪圖，拳頭清除，按 q 離開")

while True:
    ret, frame = cap.read()
    if not ret:
        break

    frame  = cv2.flip(frame, 1)
    h, w   = frame.shape[:2]

    if canvas is None:
        canvas = np.zeros_like(frame)

    rgb    = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
    result = hands.process(rgb)

    if result.multi_hand_landmarks:
        hand_lm = result.multi_hand_landmarks[0]
        lm      = hand_lm.landmark

        # 食指指尖位置
        ix = int(lm[8].x * w)
        iy = int(lm[8].y * h)

        # 手指計數判斷手勢
        tip_ids = [8, 12, 16, 20]
        pip_ids = [6, 10, 14, 18]
        finger_count = sum(
            lm[tip_ids[i]].y < lm[pip_ids[i]].y for i in range(4)
        )

        if finger_count == 1:
            # 只伸出食指：繪圖模式
            if prev_x is not None:
                cv2.line(canvas, (prev_x, prev_y), (ix, iy), color, 5)
            prev_x, prev_y = ix, iy
        elif finger_count == 0:
            # 拳頭：清除畫布
            canvas = np.zeros_like(frame)
            prev_x, prev_y = None, None
        else:
            prev_x, prev_y = None, None

        mp_drawing.draw_landmarks(frame, hand_lm, mp_hands.HAND_CONNECTIONS)

    # 疊加畫布
    output = cv2.addWeighted(frame, 0.7, canvas, 0.3, 0)
    cv2.putText(output, "食指:畫  拳頭:清除  q:離開", (10, 30),
                cv2.FONT_HERSHEY_SIMPLEX, 0.7, (255, 255, 0), 2)

    cv2.imshow("Gesture Painter", output)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

⚠️ 注意事項

cv2.flip(frame, 1) 水平翻轉很重要：不翻轉的話，MediaPipe 回傳的 Left/Right 與畫面方向相反，大拇指方向判斷會錯誤。
MediaPipe 的 handedness 是鏡像判斷：對著攝影機時，MediaPipe 判斷的「右手」實際上是你的左手（因為是鏡像）。翻轉畫面後就正確了。
z 值可用於判斷手指深度：若需要更精細的手勢（例如區分手掌朝前/朝後），可利用 z 值輔助判斷。
在黑暗環境效果較差：MediaPipe Hands 依賴 RGB 畫面，光線不足時偵測率會下降。

🎯 結語

MediaPipe Hands 提供了高精度、低延遲的手部關鍵點偵測，讓複雜的手勢辨識只需要幾何計算就能完成，不需要另外訓練模型。
下一個專案是 天堂私服 YOLOv8 物件偵測實戰，把 YOLOv8 訓練技術應用在遊戲場景中。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
MediaPipe Hands 官方文件
 MediaPipe Python Solutions

Python | OpenCV 專案：小型圖片分類專案

2026-04-16T01:00:00.000Z

📚 前言

在上一篇 車牌辨識應用 中，我們完成了結合 OCR 的辨識應用。

這一篇是 小型圖片分類專案，目標是把模型訓練與微調系列學到的遷移學習技術，整合成一個完整的端對端系統：從蒐集資料到即時攝影機推論，一次走完全流程。

範例場景：辨識「剪刀、石頭、布」三種手勢（可替換成任何你想分類的物件）。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🎯 專案目標

用攝影機蒐集自訂類別的訓練資料
以 MobileNetV2 + 遷移學習訓練分類模型
評估模型表現
整合攝影機做即時分類推論

🗃️ 專案結構

image_classifier/
├── 1_collect.py       ← 蒐集資料
├── 2_train.py         ← 訓練模型
├── 3_evaluate.py      ← 評估模型
├── 4_inference.py     ← 即時推論
├── dataset/           ← 訓練資料（自動建立）
│   ├── train/
│   │   ├── scissors/
│   │   ├── rock/
│   │   └── paper/
│   └── val/
│       ├── scissors/
│       ├── rock/
│       └── paper/
└── models/
    └── classifier.pth

💻 步驟一：蒐集訓練資料

開啟攝影機讓使用者逐類別按空白鍵蒐集訓練與驗證圖片，截取中央 ROI 後儲存。

# 1_collect.py
import cv2
import os

CLASSES    = ["scissors", "rock", "paper"]   # 修改成你的類別
TRAIN_COUNT = 200    # 每類訓練樣本數
VAL_COUNT   = 50     # 每類驗證樣本數

for cls in CLASSES:
    os.makedirs(f"dataset/train/{cls}", exist_ok=True)
    os.makedirs(f"dataset/val/{cls}",   exist_ok=True)

cap = cv2.VideoCapture(0)

for cls in CLASSES:
    for split, target in [("train", TRAIN_COUNT), ("val", VAL_COUNT)]:
        count = 0
        print(f"\n準備蒐集 [{cls}] {split} 資料，按空白鍵開始")

        # 等待使用者準備好
        while True:
            ret, frame = cap.read()
            cv2.putText(frame, f"準備好後按空白鍵：{cls} ({split})",
                        (10, 40), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 255), 2)
            cv2.imshow("Collect", frame)
            if cv2.waitKey(1) & 0xFF == ord(" "):
                break

        # 開始蒐集
        while count < target:
            ret, frame = cap.read()
            if not ret:
                break

            # 截取中央 ROI 作為訓練圖片
            h, w  = frame.shape[:2]
            size  = min(h, w) // 2
            cx, cy = w // 2, h // 2
            roi   = frame[cy-size//2:cy+size//2, cx-size//2:cx+size//2]
            roi_rsz = cv2.resize(roi, (224, 224))

            fname = os.path.join(f"dataset/{split}/{cls}", f"{count:04d}.jpg")
            cv2.imwrite(fname, roi_rsz)
            count += 1

            cv2.rectangle(frame, (cx-size//2, cy-size//2),
                          (cx+size//2, cy+size//2), (0, 255, 0), 2)
            cv2.putText(frame, f"{cls} {split}: {count}/{target}",
                        (10, 40), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2)
            cv2.imshow("Collect", frame)
            cv2.waitKey(30)   # 控制蒐集速度

cap.release()
cv2.destroyAllWindows()
print("資料蒐集完成！")

💻 步驟二：訓練模型

凍結 MobileNetV2 特徵層後只訓練分類頭，帶有增強的訓練迴圈並儲存最佳驗證準確率的模型

# 2_train.py
import torch
import torch.nn as nn
from torch.utils.data import DataLoader
from torchvision import datasets, transforms, models
import os

CLASSES  = ["scissors", "rock", "paper"]
EPOCHS   = 20
BATCH    = 32
LR       = 1e-4
DEVICE   = torch.device("cuda" if torch.cuda.is_available() else "cpu")

print(f"使用裝置：{DEVICE}")

# 資料增強
train_tf = transforms.Compose([
    transforms.RandomHorizontalFlip(),
    transforms.RandomRotation(15),
    transforms.ColorJitter(brightness=0.3, contrast=0.3),
    transforms.ToTensor(),
    transforms.Normalize([0.485, 0.456, 0.406],
                         [0.229, 0.224, 0.225]),
])
val_tf = transforms.Compose([
    transforms.ToTensor(),
    transforms.Normalize([0.485, 0.456, 0.406],
                         [0.229, 0.224, 0.225]),
])

train_ds = datasets.ImageFolder("dataset/train", transform=train_tf)
val_ds   = datasets.ImageFolder("dataset/val",   transform=val_tf)
train_dl = DataLoader(train_ds, batch_size=BATCH, shuffle=True)
val_dl   = DataLoader(val_ds,   batch_size=BATCH)

print(f"訓練集：{len(train_ds)} 張，驗證集：{len(val_ds)} 張")
print(f"類別對應：{train_ds.class_to_idx}")

# MobileNetV2 遷移學習
model = models.mobilenet_v2(weights=models.MobileNet_V2_Weights.DEFAULT)
for param in model.features.parameters():
    param.requires_grad = False

model.classifier = nn.Sequential(
    nn.Dropout(0.2),
    nn.Linear(model.last_channel, len(CLASSES)),
)
model = model.to(DEVICE)

criterion = nn.CrossEntropyLoss()
optimizer = torch.optim.Adam(model.classifier.parameters(), lr=LR)

best_acc = 0.0
os.makedirs("models", exist_ok=True)

for epoch in range(1, EPOCHS + 1):
    # --- 訓練 ---
    model.train()
    total, correct = 0, 0
    for imgs, labels in train_dl:
        imgs, labels = imgs.to(DEVICE), labels.to(DEVICE)
        optimizer.zero_grad()
        out  = model(imgs)
        loss = criterion(out, labels)
        loss.backward()
        optimizer.step()
        correct += (out.argmax(1) == labels).sum().item()
        total   += labels.size(0)
    train_acc = correct / total

    # --- 驗證 ---
    model.eval()
    total, correct = 0, 0
    with torch.no_grad():
        for imgs, labels in val_dl:
            imgs, labels = imgs.to(DEVICE), labels.to(DEVICE)
            out      = model(imgs)
            correct += (out.argmax(1) == labels).sum().item()
            total   += labels.size(0)
    val_acc = correct / total

    print(f"Epoch {epoch:02d}/{EPOCHS}  "
          f"train_acc={train_acc:.4f}  val_acc={val_acc:.4f}")

    if val_acc > best_acc:
        best_acc = val_acc
        torch.save(model.state_dict(), "models/classifier.pth")
        print(f"  ✅ 最佳模型已儲存（val_acc={val_acc:.4f}）")

print(f"\n訓練完成！最佳驗證準確率：{best_acc:.4f}")

💻 步驟三：評估模型

載入已訓練的 MobileNetV2 模型對驗證集推論，輸出各類別 Precision、Recall、F1-Score 報告‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# 3_evaluate.py
import torch
from torch.utils.data import DataLoader
from torchvision import datasets, transforms, models
from sklearn.metrics import classification_report
import torch.nn as nn
import numpy as np

CLASSES = ["scissors", "rock", "paper"]
DEVICE  = torch.device("cuda" if torch.cuda.is_available() else "cpu")

val_tf = transforms.Compose([
    transforms.ToTensor(),
    transforms.Normalize([0.485, 0.456, 0.406],
                         [0.229, 0.224, 0.225]),
])
val_ds = datasets.ImageFolder("dataset/val", transform=val_tf)
val_dl = DataLoader(val_ds, batch_size=32)

model = models.mobilenet_v2(weights=None)
model.classifier = nn.Sequential(
    nn.Dropout(0.2),
    nn.Linear(model.last_channel, len(CLASSES)),
)
model.load_state_dict(torch.load("models/classifier.pth", map_location=DEVICE))
model = model.to(DEVICE)
model.eval()

all_preds, all_labels = [], []
with torch.no_grad():
    for imgs, labels in val_dl:
        imgs   = imgs.to(DEVICE)
        preds  = model(imgs).argmax(1).cpu().numpy()
        all_preds.extend(preds)
        all_labels.extend(labels.numpy())

print(classification_report(all_labels, all_preds, target_names=CLASSES))

💻 步驟四：整合攝影機即時推論

整合 MobileNetV2 與攝影機，對畫面中央 ROI 即時分類手勢並顯示類別名稱與信心度

# 4_inference.py
import cv2
import torch
import torch.nn as nn
import numpy as np
from torchvision import transforms, models

CLASSES = ["scissors", "rock", "paper"]
DEVICE  = torch.device("cuda" if torch.cuda.is_available() else "cpu")

model = models.mobilenet_v2(weights=None)
model.classifier = nn.Sequential(
    nn.Dropout(0.2),
    nn.Linear(model.last_channel, len(CLASSES)),
)
model.load_state_dict(torch.load("models/classifier.pth", map_location=DEVICE))
model = model.to(DEVICE)
model.eval()

tf = transforms.Compose([
    transforms.ToTensor(),
    transforms.Normalize([0.485, 0.456, 0.406],
                         [0.229, 0.224, 0.225]),
])

cap = cv2.VideoCapture(0)
print("即時分類推論，按 q 離開")

while True:
    ret, frame = cap.read()
    if not ret:
        break

    h, w   = frame.shape[:2]
    size   = min(h, w) // 2
    cx, cy = w // 2, h // 2
    roi    = frame[cy-size//2:cy+size//2, cx-size//2:cx+size//2]

    # 前處理
    roi_rgb = cv2.cvtColor(cv2.resize(roi, (224, 224)), cv2.COLOR_BGR2RGB)
    from PIL import Image
    pil_img = Image.fromarray(roi_rgb)
    tensor  = tf(pil_img).unsqueeze(0).to(DEVICE)

    with torch.no_grad():
        logits = model(tensor)
        probs  = torch.softmax(logits, dim=1)[0].cpu().numpy()
        pred   = probs.argmax()

    label = f"{CLASSES[pred]}: {probs[pred]*100:.1f}%"
    cv2.rectangle(frame, (cx-size//2, cy-size//2),
                  (cx+size//2, cy+size//2), (0, 255, 0), 2)
    cv2.putText(frame, label, (10, 40),
                cv2.FONT_HERSHEY_SIMPLEX, 1.2, (0, 255, 0), 3)

    cv2.imshow("Classifier", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

⚠️ 注意事項

蒐集資料時保持背景一致：背景差異太大會讓模型學到背景而非物件本身，建議在相同背景下蒐集。
類別樣本數要均衡：每個類別樣本數差異不要超過 2 倍，否則模型會偏向樣本多的類別。
推論 ROI 與訓練 ROI 要一致：訓練時取畫面中央 ROI，推論時也要取相同位置，避免分佈偏移。

🎯 結語

這個專案把資料蒐集、模型訓練、評估、即時推論串成一條完整的 pipeline，是深度學習與 OpenCV 整合最典型的範例。
下一個專案是 MediaPipe 手勢控制應用，用 MediaPipe 的手部關鍵點做更精細的手勢辨識。

註：以上參考了
PyTorch Transfer Learning Tutorial
torchvision MobileNetV2
scikit-learn classification_report

Python | OpenCV 專案：車牌辨識應用

2026-04-15T01:00:00.000Z

📚 前言

在上一篇 即時人臉辨識系統 中，我們建立了一個完整的人臉辨識 pipeline。

這一篇要挑戰另一個經典應用：車牌辨識（License Plate Recognition，LPR）。
車牌辨識結合了邊緣偵測、輪廓分析、透視矯正與 OCR 文字辨識，是一個整合前面多個章節知識的綜合專案。

🎯 專案目標

從圖片或影片畫面中定位車牌區域
對車牌區域進行透視矯正與前處理
使用 EasyOCR 辨識車牌號碼
以影片檔或 MJPEG 串流掃描，顯示即時辨識結果

🎨 範例圖片

來源：Pexels - License Plate Image，屬於無版權圖片，可自由下載與使用。
內容：圖片車頭且有拍攝到車牌，非常適合用來做車牌辨識測試。
下載後將檔名改為 license_plate.jpg，放到專案的 assets/ 目錄下。

🛠️ 套件安裝

步驟 1：安裝 EasyOCR‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

1	pip install easyocr

步驟 2：修復 OpenCV（必做）

pip install easyocr 會連帶安裝 opencv-python-headless（無 GUI 版本），覆蓋原先的 opencv-python / opencv-contrib-python，造成下列兩種常見錯誤：

cv2.imshow → The function is not implemented. Rebuild the library with Windows, GTK+ 2.x or Cocoa support.
cv2.imread → AttributeError: module 'cv2' has no attribute 'imread'（多個 opencv 變體並存時出現）

最穩定的做法是完整清除所有 opencv 變體後再乾淨安裝：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# 1. 清除所有 opencv 變體（無論是否存在都執行一次）
pip uninstall -y opencv-python opencv-python-headless opencv-contrib-python opencv-contrib-python-headless

# 2. 確認已無殘留，以下指令應該沒有任何輸出
pip list | findstr opencv     # Windows
# pip list | grep opencv      # macOS / Linux

# 3. 乾淨安裝 contrib 版（--no-cache-dir 避免使用損壞快取）
pip install --no-cache-dir opencv-contrib-python

步驟 3：驗證安裝

import cv2
print(cv2.__file__)           # 路徑裡不應該出現 "headless"
print(cv2.__version__)
print("imread" in dir(cv2))   # 應為 True

💡 EasyOCR 首次執行時會自動下載語言模型（繁體中文 + 英文約 200MB），需要網路連線。

💡 執行時若看到 Using CPU. Note: This module is much faster with a GPU.，這是 gpu=False 的正常提示訊息，不是錯誤；本篇示範以 CPU 執行即可，若機器有 CUDA GPU 可將 easyocr.Reader(["en"], gpu=True) 以加速推論。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

💡 若 pip list 出現 WARNING: Ignoring invalid distribution -xxx，代表 site-packages 內有 ~xxx 開頭的殘留資料夾（先前安裝被中斷留下），不影響本次安裝；可執行 Remove-Item -Recurse -Force "\Lib\site-packages\~*" 清除。

💻 步驟一：從靜態圖片辨識車牌

# recognize_plate.py
import cv2
import numpy as np
import easyocr

reader = easyocr.Reader(["en"], gpu=False)   # 台灣車牌為英數字，使用英文模型即可

def find_plate_candidates(img):
    """找出可能是車牌的矩形輪廓"""
    gray    = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
    blur    = cv2.bilateralFilter(gray, 11, 17, 17)
    edges   = cv2.Canny(blur, 30, 200)

    contours, _ = cv2.findContours(edges, cv2.RETR_TREE, cv2.CHAIN_APPROX_SIMPLE)
    contours     = sorted(contours, key=cv2.contourArea, reverse=True)[:20]

    candidates = []
    for c in contours:
        peri   = cv2.arcLength(c, True)
        approx = cv2.approxPolyDP(c, 0.018 * peri, True)
        if len(approx) == 4:
            candidates.append(approx)

    return candidates

def crop_plate(img, contour):
    """根據輪廓裁切車牌區域"""
    x, y, w, h = cv2.boundingRect(contour)
    return img[y:y+h, x:x+w], (x, y, w, h)

def preprocess_plate(plate_img):
    """車牌影像前處理"""
    gray    = cv2.cvtColor(plate_img, cv2.COLOR_BGR2GRAY)
    resized = cv2.resize(gray, (300, 80))
    _, binary = cv2.threshold(resized, 0, 255,
                              cv2.THRESH_BINARY + cv2.THRESH_OTSU)
    return binary

def recognize_plate(img_path):
    img = cv2.imread(img_path)
    if img is None:
        print("圖片讀取失敗")
        return

    candidates = find_plate_candidates(img)

    if not candidates:
        print("未找到車牌候選區域")
        return

    # 取面積最大的候選框
    plate_region, (x, y, w, h) = crop_plate(img, candidates[0])
    processed = preprocess_plate(plate_region)

    results = reader.readtext(processed, allowlist="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-")

    plate_text = " ".join([r[1] for r in results if r[2] > 0.3])
    print(f"辨識結果：{plate_text if plate_text else '無法辨識'}")

    # 繪製標記
    cv2.rectangle(img, (x, y), (x + w, y + h), (0, 255, 0), 3)
    cv2.putText(img, plate_text, (x, y - 10),
                cv2.FONT_HERSHEY_SIMPLEX, 1.0, (0, 255, 0), 2)

    cv2.imshow("Result", img)
    cv2.imshow("Plate", processed)
    cv2.waitKey(0)
    cv2.destroyAllWindows()

recognize_plate("assets/license_plate.jpg")

圖：偵測圖片中的車牌輪廓區域，透過 Otsu 二值化前處理後使用 EasyOCR 辨識車牌號碼

💻 步驟二：改善辨識率的前處理

對四角點車牌區域進行透視矯正，將傾斜或仰角拍攝的車牌展平為正面視角‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

光線與角度影響辨識率很大，可加入透視矯正提升準確度：

# perspective_transform.py
def four_point_transform(img, pts):
    """將四個角點矩形區域進行透視矯正"""
    pts = pts.reshape(4, 2).astype(np.float32)

    # 排序角點：左上、右上、右下、左下
    s    = pts.sum(axis=1)
    diff = np.diff(pts, axis=1)
    rect = np.array([
        pts[np.argmin(s)],    # 左上
        pts[np.argmin(diff)], # 右上
        pts[np.argmax(s)],    # 右下
        pts[np.argmax(diff)], # 左下
    ], dtype=np.float32)

    w = max(
        np.linalg.norm(rect[1] - rect[0]),
        np.linalg.norm(rect[2] - rect[3]),
    )
    h = max(
        np.linalg.norm(rect[3] - rect[0]),
        np.linalg.norm(rect[2] - rect[1]),
    )

    dst = np.array([[0, 0], [w, 0], [w, h], [0, h]], dtype=np.float32)
    M   = cv2.getPerspectiveTransform(rect, dst)
    return cv2.warpPerspective(img, M, (int(w), int(h)))

💻 步驟三：從影片或串流辨識車牌

步驟一的輪廓法（approxPolyDP）適合乾淨的車牌近照，但在真實行車影片中背景雜訊過多，常常找不到四邊形或找錯位置，再加上只取「面積最大」的候選框，命中率很低。

本步驟改為直接把整幀交給 EasyOCR 內建的文字偵測模型（CRAFT）偵測所有文字區塊，再用信心度與長寬比挑出最像車牌的那一塊，比輪廓法穩定很多。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

同時以影片檔或 MJPEG 串流取代即時攝影機，不需要攝影機設備也不涉及個人隱私即可完整練習。建議使用行車記錄器影片、停車場監控影片或自行拍攝的車輛影片作為測試素材；若需要即時畫面，也可改用手機 App（例如 IP Webcam）提供的 MJPEG 串流 URL，程式邏輯完全相同。

# scan_video.py
import cv2
import easyocr
import time

reader      = easyocr.Reader(["en"], gpu=False)
video_path  = "assets/traffic.mp4"   # 影片檔或 MJPEG 串流 URL 皆可
cap         = cv2.VideoCapture(video_path)
if not cap.isOpened():
    print(f"無法開啟影片：{video_path}")
    exit()

last_result = ""
last_bbox   = None
last_time   = 0
interval    = 1.0   # 每秒辨識一次，避免 OCR 頻繁呼叫拖慢幀率

print("影片辨識啟動，按 q 離開")

while True:
    ret, frame = cap.read()
    if not ret:
        print("影片播放完畢")
        break

    now = time.time()
    if now - last_time > interval:
        # EasyOCR 直接在整幀畫面偵測文字，比輪廓法更穩定
        results = reader.readtext(
            frame,
            allowlist="ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-",
        )

        # 過濾：信心度 > 0.4、長寬比接近車牌比例（約 2:1 ~ 5:1）
        best = None
        for bbox, text, conf in results:
            if conf < 0.4:
                continue
            (tl, tr, br, bl) = bbox
            w = abs(tr[0] - tl[0])
            h = abs(bl[1] - tl[1])
            if h == 0 or not (1.5 < w / h < 6):
                continue
            if best is None or conf > best[2]:
                best = (bbox, text.replace(" ", ""), conf)

        if best:
            last_bbox, last_result, _ = best
        last_time = now

    if last_bbox is not None and last_result:
        tl = last_bbox[0]
        br = last_bbox[2]
        pt1 = (int(tl[0]), int(tl[1]))
        pt2 = (int(br[0]), int(br[1]))
        cv2.rectangle(frame, pt1, pt2, (0, 255, 0), 2)
        cv2.putText(frame, last_result, (pt1[0], pt1[1] - 10),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2)

    cv2.imshow("License Plate Recognition", frame)
    if cv2.waitKey(30) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

圖：讀取行車影片，EasyOCR 在整幀畫面偵測所有文字後以信心度與長寬比過濾，標出最可能的車牌並顯示辨識結果

📷 改用即時攝影機：將 video_path = "assets/traffic.mp4" 改為 cap = cv2.VideoCapture(0)，即可改為即時攝影機辨識，程式邏輯完全相同。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

📡 改用 MJPEG 串流：將 video_path 改為 MJPEG URL（例如手機 App「IP Webcam」提供的 http://<手機 IP>:8080/video），即可從手機或 IP 攝影機取得即時畫面。

💡 效能提示：在整幀畫面跑 OCR 比裁切小區域慢，CPU 環境下一次約 0.5~2 秒；interval = 1.0 已經留了緩衝，若仍卡頓可調高到 2.0，或將畫面先縮小（frame = cv2.resize(frame, (640, 360))）再送 OCR。

⚠️ 注意事項

輪廓法的侷限性：approxPolyDP 找四邊形的方法在複雜背景下容易失效，若需要更穩健的車牌定位，建議改用 YOLOv8 訓練一個車牌偵測模型（定位更精準）。
OCR 不設定 allowlist 會辨識出許多雜訊：台灣車牌只有英數字與 -，設定 allowlist 可大幅提升準確率。
即時辨識不要每幀都跑 OCR：EasyOCR 速度較慢，用時間間隔（interval）控制呼叫頻率，避免幀率過低。
繁體中文車牌：若需辨識含中文字（如機車牌），將 easyocr.Reader(["en"]) 改為 easyocr.Reader(["ch_tra", "en"])。
MJPEG 串流延遲：透過網路讀取 MJPEG 串流時若出現畫面卡頓，可降低串流解析度或改回本機影片檔測試，避免網路狀況影響辨識結果。
EasyOCR 安裝會覆蓋 OpenCV：若執行時出現 cv2.imshow 未實作或 cv2 has no attribute 'imread' 等錯誤，請回頭依「套件安裝」的完整步驟清除所有 opencv 變體後再重新安裝 opencv-contrib-python。切記僅執行 pip uninstall opencv-python-headless 再安裝往往不夠，需一次移除所有變體才能避免殘留衝突。

📊 進階方向

用 YOLOv8 取代輪廓法定位車牌：準確度大幅提升，適合多車輛場景
加入資料庫查詢：辨識到車牌後，查詢黑名單或收費系統
多幀投票：同一輛車連續辨識 5 幀，取出現最多次的號碼作為最終結果，提升準確率

🎯 結語

車牌辨識整合了輪廓分析、透視矯正與 OCR，是一個能實際部署的完整應用。
下一篇將進入 OpenCV 專案：小型圖片分類專案，把模型訓練篇學到的遷移學習技術整合成一個端對端的分類系統。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
EasyOCR GitHub
OpenCV 官方文件 — Contour Features
OpenCV 官方文件 — Geometric Transformations

Python | OpenCV 專案：即時人臉辨識系統

2026-04-14T01:00:00.000Z

📚 前言

在上一篇 即時濾鏡相機 中，我們完成了第一個整合專案。

這一篇進入更有挑戰性的應用：即時人臉辨識系統。
不只是「偵測到臉」，而是能辨識出「這張臉是誰」，並在即時畫面中顯示姓名與信心度。

這個專案不依賴深度學習框架，完全使用 OpenCV 內建的 LBPH（Local Binary Pattern Histogram）演算法即可完成。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🎯 專案目標

蒐集多人的人臉樣本
訓練 LBPH 辨識模型
影片辨識，顯示姓名與信心度
支援隨時新增人員（重新蒐集 + 重新訓練）

🗃️ 專案結構

face_recognition/
├── assets/          ← 素材影片（每人一段）
│   ├── person_a.mp4
│   ├── person_b.mp4
│   └── test.mp4
├── 1_collect.py     ← 步驟一：從影片蒐集人臉樣本
├── 2_train.py       ← 步驟二：訓練辨識模型
├── 3_recognize.py   ← 步驟三：影片辨識
├── dataset/         ← 蒐集的人臉圖片（自動建立）
│   ├── 0_PersonA/
│   ├── 1_PersonB/
│   └── ...
└── models/          ← 儲存訓練好的模型（自動建立）
    ├── face_model.yml
    └── label_map.json

🎬 準備影片素材

本篇以影片檔取代即時攝影機，不需要攝影機設備也不涉及個人隱私即可完整練習。

建議使用公開演講影片（例如 TED Talks，採 Creative Commons 授權），正面清晰、光線穩定，非常適合人臉辨識練習。每位人員各準備一段演講影片，另外再準備一段測試用影片（建議選不同段落，讓辨識測試更有說服力）。

使用 yt-dlp 下載：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# install_yt_dlp.sh
pip install yt-dlp

# 每位人員各下載一段演講影片
yt-dlp -f "mp4[height<=720]" -o "assets/person_a.mp4" [影片 URL]
yt-dlp -f "mp4[height<=720]" -o "assets/person_b.mp4" [影片 URL]

此處示範使用 TED Talks 的兩部影片：

How Nearly Dying Helped Me Discover My Own Cure (and Many More) | David Fajgenbaum | TED

Why You Should Spend Less Time with Your Kids | Lenore Skenazy | TED

1
2

yt-dlp -f "mp4[height<=720]" -o "assets/person_a.mp4" https://youtu.be/sb34MfJjurc?si=2EmEQuSZXCo7QOq_                                                                      
yt-dlp -f "mp4[height<=720]" -o "assets/person_b.mp4" https://youtu.be/whaesnYloMQ?si=GO29UO0xsB00NCgQ

person_a 影片後處理兩段影片分別為訓練影片與驗證影片

1 2	40 - 60 秒 ⭢ person_a 00_00_40-00_01_00.mp4 60 - 120 秒 ⭢ person_a 00_01_00-00_01_20.mp4

person_b 影片後處理兩段影片分別為訓練影片與驗證影片

1 2	40 - 60 秒 ⭢ person_b 00_00_40-00_01_00.mp4 60 - 120 秒 ⭢ person_b 00_01_00-00_01_20.mp4

💻 步驟一：蒐集人臉樣本

# 1_collect.py
import cv2
import os

# ===== 設定 =====
person_id      = 0                       # 每位人員指定一個唯一 ID（從 0 開始遞增）
person_name    = "PersonA"               # 人員姓名
video_path     = "assets/person_a.mp4"   # 來源影片路徑
sample_count   = 100                     # 目標蒐集樣本數
frame_interval = 3                       # 每 N 幀處理一次，避免連續幀過於相似
# ================

save_dir = f"dataset/{person_id}_{person_name}"
os.makedirs(save_dir, exist_ok=True)

face_cascade = cv2.CascadeClassifier(
    cv2.data.haarcascades + "haarcascade_frontalface_default.xml"
)

cap = cv2.VideoCapture(video_path)
if not cap.isOpened():
    print(f"無法開啟影片：{video_path}")
    exit()

count     = 0
frame_idx = 0
print(f"開始從影片蒐集 {person_name} 的人臉樣本，目標 {sample_count} 張")

while count < sample_count:
    ret, frame = cap.read()
    if not ret:
        print("影片播放完畢")
        break

    frame_idx += 1
    if frame_idx % frame_interval != 0:
        continue

    gray  = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    faces = face_cascade.detectMultiScale(gray, 1.3, 5)

    for (x, y, w, h) in faces:
        face_img = gray[y:y+h, x:x+w]
        face_rsz = cv2.resize(face_img, (200, 200))
        filename = os.path.join(save_dir, f"{count:04d}.jpg")
        cv2.imwrite(filename, face_rsz)
        count += 1

        cv2.rectangle(frame, (x, y), (x+w, y+h), (0, 255, 0), 2)
        cv2.putText(frame, f"{count}/{sample_count}", (x, y - 10),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.7, (0, 255, 0), 2)

    cv2.imshow("Collecting", frame)
    if cv2.waitKey(30) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()
print(f"完成！共蒐集 {count} 張樣本，儲存於 {save_dir}")

圖：從影片逐幀偵測人臉，每隔 N 幀截取一次，自動儲存灰階人臉圖片，累積到指定樣本數後結束

💡 每位人員執行一次，修改 person_id、person_name 與 video_path 後重新執行，即可累積多人資料集。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

📷 改用即時攝影機：將 video_path 那行改為 cap = cv2.VideoCapture(0)，並移除 frame_interval 的跳幀邏輯（或設為 1），即可改用攝影機即時蒐集，程式邏輯完全相同。

💻 步驟二：訓練辨識模型

# 2_train.py
import cv2
import numpy as np
import os
import json

dataset_dir = "dataset"
faces       = []
labels      = []
label_map   = {}    # id → name

for folder in sorted(os.listdir(dataset_dir)):
    folder_path = os.path.join(dataset_dir, folder)
    if not os.path.isdir(folder_path):
        continue

    # 資料夾命名規則：{id}_{name}
    parts       = folder.split("_", 1)
    person_id   = int(parts[0])
    person_name = parts[1] if len(parts) > 1 else folder
    label_map[person_id] = person_name

    for fname in os.listdir(folder_path):
        if not fname.lower().endswith(".jpg"):
            continue
        img_path = os.path.join(folder_path, fname)
        img      = cv2.imread(img_path, cv2.IMREAD_GRAYSCALE)
        if img is not None:
            faces.append(img)
            labels.append(person_id)

print(f"載入完成：{len(faces)} 張樣本，{len(label_map)} 位人員")
print(f"人員清單：{label_map}")

recognizer = cv2.face.LBPHFaceRecognizer_create()
recognizer.train(faces, np.array(labels))

os.makedirs("models", exist_ok=True)
recognizer.save("models/face_model.yml")

with open("models/label_map.json", "w", encoding="utf-8") as f:
    json.dump({str(k): v for k, v in label_map.items()}, f, ensure_ascii=False)

print("訓練完成！模型已儲存至 model/face_model.yml")

圖：讀取所有人員的人臉樣本，使用 LBPH 演算法訓練辨識模型並儲存為 yml 與 JSON 標籤檔

⚠️ cv2.face 需要 opencv-contrib-python：pip install opencv-contrib-python‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

💻 步驟三：影片辨識

# 3_recognize.py
import cv2
import json

# 載入模型與標籤
recognizer = cv2.face.LBPHFaceRecognizer_create()
recognizer.read("models/face_model.yml")

with open("models/label_map.json", encoding="utf-8") as f:
    raw_map   = json.load(f)
    label_map = {int(k): v for k, v in raw_map.items()}

face_cascade = cv2.CascadeClassifier(
    cv2.data.haarcascades + "haarcascade_frontalface_default.xml"
)

CONFIDENCE_THRESHOLD = 80
video_path = "assets/test.mp4"

cap = cv2.VideoCapture(video_path)
if not cap.isOpened():
    print(f"無法開啟影片：{video_path}")
    exit()
print("影片辨識啟動，按 q 離開")

while True:
    ret, frame = cap.read()
    if not ret:
        print("影片播放完畢")
        break

    gray  = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    faces = face_cascade.detectMultiScale(gray, 1.3, 5)

    for (x, y, w, h) in faces:
        face_img = gray[y:y+h, x:x+w]
        face_rsz = cv2.resize(face_img, (200, 200))

        label, confidence = recognizer.predict(face_rsz)

        # LBPH：confidence 越低代表越相似（0 = 完全一致）
        if confidence < CONFIDENCE_THRESHOLD:
            name  = label_map.get(label, "Unknown")
            color = (0, 255, 0)
            text  = f"{name} ({confidence:.1f})"
        else:
            name  = "Unknown"
            color = (0, 0, 255)
            text  = f"Unknown ({confidence:.1f})"

        cv2.rectangle(frame, (x, y), (x+w, y+h), color, 2)
        cv2.putText(frame, text, (x, y - 10),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.7, color, 2)

    cv2.imshow("Face Recognition", frame)
    if cv2.waitKey(30) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

圖：載入 LBPH 模型對測試影片進行辨識，依信心度顯示姓名或 Unknown 並標示邊界框

📷 改用即時攝影機：將 video_path = "assets/test.mp4" 改為 cap = cv2.VideoCapture(0)，即可改為即時攝影機辨識，程式邏輯完全相同。

💻 新增人員

只需：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

修改 1_collect.py 的 person_id（遞增）、person_name 與 video_path，重新執行蒐集
重新執行 2_train.py 訓練（會自動載入所有已蒐集的資料）
重新執行 3_recognize.py

不需要修改任何辨識邏輯。

⚠️ 注意事項

影片品質：蒐集樣本的影片建議選正面清晰、光線均勻的片段，避免快速搖晃或逆光。
LBPH 對光線敏感：蒐集影片與測試影片的光線環境差異越小，辨識率越高。
信心度閾值需要調整：CONFIDENCE_THRESHOLD = 80 是參考值，不同影片品質與光線條件可能需要調高或調低。
樣本多樣性：若影片角度過於單一，辨識率可能偏低，建議選取包含多種頭部角度的片段。
frame_interval 設定：影片較短但樣本需求量大時可調低；角度變化緩慢時可調高以增加多樣性。
opencv-contrib-python 與 opencv-python 不能同時安裝：若已安裝 opencv-python，需先 pip uninstall opencv-python 再安裝 opencv-contrib-python。

🎯 結語

LBPH 人臉辨識輕量且不需要 GPU，適合在本機快速建立小規模的人員辨識系統。
若需要更高準確度（例如跨光線、跨角度），可考慮改用 face_recognition 套件（基於深度學習的人臉嵌入向量）。

下一篇將進入 OpenCV 專案：車牌辨識應用，結合輪廓分析與 OCR，識別圖片中的車牌號碼。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
OpenCV 官方文件 — Face Recognition
OpenCV LBPH Face Recognizer

Python | OpenCV 專案：即時濾鏡相機

2026-04-13T01:00:00.000Z

📚 前言

在上一篇 OpenCV QR Code 與 BarCode 辨識 中，我們完成了條碼辨識的實作，正式踏入 專案實作篇。

這一篇是第一個整合專案：即時濾鏡相機。
目標是把前面學過的色彩轉換、模糊、形態學、繪圖等功能整合在一起，做出一個可用鍵盤切換濾鏡的即時相機程式。沒有攝影機也沒關係，程式同時支援以影片檔作為輸入來源，效果完全相同。

🎯 專案目標

攝影機或影片檔即時預覽
按鍵切換 10 種以上的濾鏡效果
畫面顯示目前濾鏡名稱
按 s 截圖儲存
按 q 離開

🗃️ 專案結構

filter_camera/
├── assets/          ← 測試影片（無攝影機時使用）
│   └── sample.mp4
├── output/          ← 截圖輸出
├── main.py          ← 主程式
└── filters.py       ← 濾鏡函式集合

🎨 範例影片

來源：Pexels - Code，屬於無版權影片，可自由下載與使用。
下載後將檔名改為 sample.mp4，放到專案的 assets/ 目錄下。

💻 filters.py — 濾鏡函式集合

定義灰階、模糊、邊緣、復古、負片、銳化、浮雕、卡通、馬賽克、暖冷色調等 12 種濾鏡函式

# filters.py
import cv2
import numpy as np

def original(frame):
    return frame

def grayscale(frame):
    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    return cv2.cvtColor(gray, cv2.COLOR_GRAY2BGR)

def blur(frame):
    return cv2.GaussianBlur(frame, (21, 21), 0)

def edge(frame):
    gray  = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    edges = cv2.Canny(gray, 50, 150)
    return cv2.cvtColor(edges, cv2.COLOR_GRAY2BGR)

def sepia(frame):
    kernel = np.array([[0.272, 0.534, 0.131],
                       [0.349, 0.686, 0.168],
                       [0.393, 0.769, 0.189]])
    result = cv2.transform(frame.astype(np.float32), kernel)
    return np.clip(result, 0, 255).astype(np.uint8)

def invert(frame):
    return cv2.bitwise_not(frame)

def sharpen(frame):
    kernel = np.array([[ 0, -1,  0],
                       [-1,  5, -1],
                       [ 0, -1,  0]])
    return cv2.filter2D(frame, -1, kernel)

def emboss(frame):
    kernel = np.array([[-2, -1,  0],
                       [-1,  1,  1],
                       [ 0,  1,  2]])
    result = cv2.filter2D(frame, -1, kernel) + 128
    return np.clip(result, 0, 255).astype(np.uint8)

def cartoon(frame):
    gray     = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    gray_blur = cv2.medianBlur(gray, 5)
    edges    = cv2.adaptiveThreshold(gray_blur, 255,
                                     cv2.ADAPTIVE_THRESH_MEAN_C,
                                     cv2.THRESH_BINARY, 9, 9)
    color    = cv2.bilateralFilter(frame, 9, 300, 300)
    return cv2.bitwise_and(color, color, mask=edges)

def mosaic(frame, block=20):
    h, w  = frame.shape[:2]
    small = cv2.resize(frame, (w // block, h // block),
                       interpolation=cv2.INTER_LINEAR)
    return cv2.resize(small, (w, h), interpolation=cv2.INTER_NEAREST)

def warm(frame):
    # 提高紅/黃色調
    lut = np.arange(256, dtype=np.uint8)
    lut_r = np.clip(lut * 1.2, 0, 255).astype(np.uint8)
    lut_b = np.clip(lut * 0.8, 0, 255).astype(np.uint8)
    b, g, r = cv2.split(frame)
    return cv2.merge([cv2.LUT(b, lut_b), g, cv2.LUT(r, lut_r)])

def cool(frame):
    # 提高藍色調
    lut   = np.arange(256, dtype=np.uint8)
    lut_r = np.clip(lut * 0.8, 0, 255).astype(np.uint8)
    lut_b = np.clip(lut * 1.2, 0, 255).astype(np.uint8)
    b, g, r = cv2.split(frame)
    return cv2.merge([cv2.LUT(b, lut_b), g, cv2.LUT(r, lut_r)])

# 濾鏡清單：(名稱, 函式)
FILTERS = [
    ("原始畫面",     original),
    ("灰階",         grayscale),
    ("模糊",         blur),
    ("邊緣",         edge),
    ("復古",         sepia),
    ("負片",         invert),
    ("銳化",         sharpen),
    ("浮雕",         emboss),
    ("卡通",         cartoon),
    ("馬賽克",       mosaic),
    ("暖色調",       warm),
    ("冷色調",       cool),
]

💻 main.py — 主程式

cv2.VideoCapture() 同時支援攝影機 index（整數）與影片檔路徑（字串），因此只需在開頭以 sys.argv 判斷來源，其餘邏輯完全不變。影片播完後以 CAP_PROP_POS_FRAMES seek 回第 0 幀即可無縫循環，濾鏡效果的呈現與真實攝影機沒有差異。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# main.py
import cv2
import os
import sys
from datetime import datetime
from filters import FILTERS

# python main.py                    → 攝影機 (index 0)
# python main.py assets/sample.mp4  → 影片檔
source       = sys.argv[1] if len(sys.argv) > 1 else 0
is_video     = isinstance(source, str)
cap          = cv2.VideoCapture(source)
if not cap.isOpened():
    print("無法開啟來源，請確認攝影機或影片路徑是否正確")
    exit()
filter_index = 0
save_dir     = "output"
os.makedirs(save_dir, exist_ok=True)

print("操作說明：")
print("  ← / → 方向鍵  切換濾鏡")
print("  s              截圖儲存")
print("  q              離開")

while True:
    ret, frame = cap.read()
    if not ret:
        if is_video:                           # 影片播完後從頭循環
            cap.set(cv2.CAP_PROP_POS_FRAMES, 0)
            continue
        break

    name, func = FILTERS[filter_index]

    try:
        output = func(frame)
    except Exception as e:
        print(f"濾鏡 [{name}] 發生錯誤：{e}")
        output = frame

    cv2.imshow("Filter Camera", output)

    key = cv2.waitKey(1) & 0xFF

    if key == ord("q"):
        break
    elif key == ord("s"):
        ts       = datetime.now().strftime("%Y%m%d_%H%M%S")
        filename = os.path.join(save_dir, f"{ts}.jpg")
        cv2.imwrite(filename, output)
        print(f"截圖已儲存：{filename}")
    elif key == 81 or key == ord("a"):   # ← 或 a
        filter_index = (filter_index - 1) % len(FILTERS)
    elif key == 83 or key == ord("d"):   # → 或 d
        filter_index = (filter_index + 1) % len(FILTERS)

cap.release()
cv2.destroyAllWindows()

圖：開啟影片檔，以方向鍵或是(a / d)切換濾鏡並在畫面顯示名稱，按 s 截圖儲存，按 q 離開

💻 執行方式

cd filter_camera

# 使用攝影機
python main.py

# 使用影片檔（不需攝影機）
python main.py assets/sample.mp4

⚠️ 注意事項

影片檔模式自動循環：影片播完會自動從頭播放，適合無攝影機環境展示所有濾鏡效果；若要單次播放，移除 if is_video 的 seek 邏輯即可。
方向鍵的 keycode 因平台而異：Windows 上 ← 為 81、→ 為 83；若方向鍵無效，可改用 a / d 切換。
卡通濾鏡速度較慢：bilateralFilter 計算量大，幀率可能下降，可縮小 d（直徑）參數或降低解析度改善。
截圖目錄：預設儲存在執行目錄下的 output/，初次執行會自動建立。

🎯 結語

即時濾鏡相機整合了色彩轉換、濾波、形態學、LUT 色調調整等多種技術，是一個能快速驗證學習成果的入門專案。

下一篇將進入 OpenCV 專案：即時人臉辨識系統，把人臉偵測進一步升級為能辨識具體身份的系統。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
OpenCV 官方文件 — Image Filtering
OpenCV 官方文件 — Color Conversions

Python | OpenCV QR Code 與 BarCode 辨識

2026-04-12T01:00:00.000Z

📚 前言

在 與 OpenCV 整合推論 中，我們學會了如何把深度學習模型整合進 OpenCV 的視訊流程。

這一篇介紹一個非常實用的應用：QR Code 與 BarCode 辨識。
從商品掃碼、入場驗票到倉儲管理，條碼掃描是日常中最常見的電腦視覺應用之一，而且實作起來相對簡單。

🎨 範例圖片

這裡我們使用 BarcodeOcean 提供的條碼產生器：BarcodeOcean。
使用「生成QR Code」產生後，下載將檔名改為 qrcode.png，放在 assets/，即可用於以下各範例。
使用「生成條碼」產生後，下載將檔名改為 Barcode.png，放在 assets/，即可用於以下各範例。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🛠️ 套件安裝

OpenCV 內建 QRCodeDetector 可解碼 QR Code，Barcode 辨識則建議搭配 pyzbar 套件：

1 2	pip install pyzbar pip install qrcode[pil] # 若需要產生 QR Code

💡 Windows 使用者若安裝 pyzbar 後出現 zbar DLL not found 錯誤，需另外下載 zbar DLL：
可安裝 pip install pyzbar-win32-fix 或從 zbar 官網下載 DLL 後放入 %SystemRoot%\System32。

💻 使用 OpenCV 解碼 QR Code

OpenCV 內建 cv2.QRCodeDetector，不需要額外套件即可解碼 QR Code：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# decode_qrcode_opencv.py
import cv2

img = cv2.imread("assets/qrcode.png")
detector = cv2.QRCodeDetector()

# detectAndDecode：同時偵測位置與解碼
# 回傳三個值：解碼字串、邊框座標、灰度圖；灰度圖不需要用到，以 _ 表示丟棄
data, bbox, _ = detector.detectAndDecode(img)

if data:
    print(f"QR Code 內容：{data}")

    # bbox 為四個角點座標，繪製邊框
    if bbox is not None:
        bbox = bbox.astype(int)   # bbox 預設為 float，繪圖函式需要整數座標
        for i in range(len(bbox[0])):
            pt1 = tuple(bbox[0][i])
            pt2 = tuple(bbox[0][(i + 1) % len(bbox[0])])
            cv2.line(img, pt1, pt2, (0, 255, 0), 2)

    cv2.putText(img, data, (10, 30),
                cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2)
else:
    print("未偵測到 QR Code")

cv2.imshow("QR Code", img)
cv2.waitKey(0)
cv2.destroyAllWindows()

圖：使用 OpenCV 內建 QRCodeDetector 解碼圖片中的 QR Code，繪製邊框並顯示解碼內容

💻 使用 pyzbar 解碼 QR Code 與 BarCode

pyzbar 支援多種條碼格式（QR Code、Code128、EAN-13、EAN-8、UPC-A 等），是更通用的選擇：

# decode_barcode_pyzbar.py
import cv2
from pyzbar import pyzbar

img = cv2.imread("assets/Barcode.png")

# decode 會回傳圖片中所有偵測到的條碼
barcodes = pyzbar.decode(img)

for barcode in barcodes:
    # barcode.data 是 bytes（二進位），需要 decode 成一般字串才能印出或比對
    data      = barcode.data.decode("utf-8")
    bc_type   = barcode.type        # 條碼格式，例如：QRCODE、CODE128、EAN13

    # barcode.rect：(x, y, w, h)
    x, y, w, h = barcode.rect
    cv2.rectangle(img, (x, y), (x + w, y + h), (0, 255, 0), 2)

    label = f"{bc_type}: {data}"
    cv2.putText(img, label, (x, y - 10),
                cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2)
    print(f"類型：{bc_type}，內容：{data}")

cv2.imshow("Barcode", img)
cv2.waitKey(0)
cv2.destroyAllWindows()

圖：使用 pyzbar 解碼圖片中的 QR Code 或 BarCode，繪製矩形框並輸出條碼類型與內容‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

💻 即時攝影機掃描

結合攝影機做即時掃描，是最常見的應用場景：

# scan_camera.py
import cv2
from pyzbar import pyzbar

cap = cv2.VideoCapture(0)   # 0 表示第一支攝影機；若有多支可改為 1、2…
if not cap.isOpened():
    print("無法開啟攝影機，請確認設備是否連接")
    exit()
print("對準條碼，按 q 離開")

scanned = set()   # 避免重複顯示同一條碼

while True:
    ret, frame = cap.read()
    if not ret:
        break

    barcodes = pyzbar.decode(frame)

    for barcode in barcodes:
        data    = barcode.data.decode("utf-8")
        bc_type = barcode.type

        x, y, w, h = barcode.rect
        cv2.rectangle(frame, (x, y), (x + w, y + h), (0, 255, 0), 2)
        cv2.putText(frame, f"{bc_type}: {data}", (x, y - 10),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2)

        if data not in scanned:
            scanned.add(data)
            print(f"掃描到 [{bc_type}]：{data}")

    cv2.imshow("Scanner", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

📝 註：由於本身沒有攝影鏡頭，所以無法示範效果。

💻 批次處理圖片資料夾

需要批次掃描大量圖片時（如倉儲盤點照片）：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# batch_scan.py
import cv2
import os
from pyzbar import pyzbar

img_dir = "assets/"
results = []

for fname in os.listdir(img_dir):
    if not fname.lower().endswith((".jpg", ".jpeg", ".png")):
        continue

    img      = cv2.imread(os.path.join(img_dir, fname))
    barcodes = pyzbar.decode(img)

    for barcode in barcodes:
        data    = barcode.data.decode("utf-8")
        bc_type = barcode.type
        results.append({"file": fname, "type": bc_type, "data": data})
        print(f"{fname}  [{bc_type}]  {data}")

print(f"\n共掃描 {len(results)} 筆條碼")

圖：批次掃描目錄中的所有圖片，輸出每張圖片中偵測到的條碼類型、內容與統計筆數

💻 產生 QR Code

使用 qrcode 套件產生自訂的 QR Code 圖片：

# generate_qrcode.py
import qrcode
import os

output_dir = "output"

# 如果 output 資料夾不存在，就自動建立
if not os.path.exists(output_dir):
    os.makedirs(output_dir)
    print(f"已自動建立資料夾：{output_dir}")

# 基本 QR Code
data1 = "https://morosedog.gitlab.io/"

img1 = qrcode.make(data1)

# 存到 output 資料夾
save_path1 = os.path.join(output_dir, "qrcode_basic.png")
img1.save(save_path1)
print(f"基本 QR Code 已儲存 → {save_path1}")

# 自訂樣式 QR Code
qr = qrcode.QRCode(
    version=1,
    error_correction=qrcode.constants.ERROR_CORRECT_H,   # 高容錯
    box_size=10,
    border=4,
)

qr.add_data("Hello, OpenCV!")
qr.make(fit=True)

img2 = qr.make_image(fill_color="black", back_color="white")

# 存到 output 資料夾
save_path2 = os.path.join(output_dir, "qrcode_custom.png")
img2.save(save_path2)
print(f"自訂 QR Code 已儲存 → {save_path2}")

print("✅ 所有 QR Code 產生完成！")

圖：使用 qrcode 套件產生基本與自訂樣式的 QR Code 圖片，設定容錯等級、格子大小與邊框‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

圖：QR Code 錯誤修正等級（Error Correction Level）比較表，包含各等級的可容錯比例與建議使用情境

💻 用 OpenCV 驗證產生的 QR Code

產生後立刻用 OpenCV 驗證是否可正常讀取：

# verify_qrcode.py
import qrcode
import cv2
import numpy as np
import os

# 產生 QR Code
data = "驗證測試字串"          # ← 你要驗證的內容

# 使用 qrcode 產生 QR Code（PIL Image）
qr_pil = qrcode.make(data)

# PIL → OpenCV 格式轉換 
rgb_array = np.array(qr_pil.convert("RGB"))        # PIL Image → numpy array (RGB)
img = cv2.cvtColor(rgb_array, cv2.COLOR_RGB2BGR)   # RGB → BGR (OpenCV 格式)

# 驗證 QR Code
detector = cv2.QRCodeDetector()
decoded_data, bbox, _ = detector.detectAndDecode(img)

print(f"原始內容：{data}")
print(f"解碼結果：{decoded_data}")

if decoded_data == data:
    print("✅ 驗證成功！產生與解碼一致")
else:
    print("❌ 驗證失敗")

# 儲存圖片到 output 資料夾
output_dir = "output"
if not os.path.exists(output_dir):
    os.makedirs(output_dir)

save_path = os.path.join(output_dir, "qrcode_verify.png")
cv2.imwrite(save_path, img)
print(f"圖片已儲存至：{save_path}")

# 顯示圖片
cv2.imshow("Generated QR Code", img)
cv2.waitKey(0)
cv2.destroyAllWindows()

圖：產生 QR Code 後立即用 OpenCV QRCodeDetector 解碼驗證，確認生成與讀取結果一致‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

⚠️ 注意事項

圖片品質影響辨識率：模糊、光線不足、角度過斜都會降低辨識率。實際應用時建議先做影像前處理（灰階、銳化）再解碼。
pyzbar 比 OpenCV 內建的 QRCodeDetector 更通用：OpenCV 只能解 QR Code，pyzbar 支援十幾種條碼格式，建議以 pyzbar 為主。
pyzbar 在 macOS 上需要額外安裝 zbar：brew install zbar。
容錯等級越高，QR Code 越複雜：ERROR_CORRECT_H 雖然耐用，但產生的圖案較密集，距離過遠時反而難以掃描。
scanned set 防止重複觸發：即時掃描時同一個條碼可能連續數幀都被偵測到，用 set 記錄已掃描的內容可避免重複處理。

📊 應用場景

門票驗證：掃描入場 QR Code，即時查詢資料庫確認有效性。
商品盤點：批次掃描倉庫照片，自動統計 EAN-13 條碼數量。
名片辨識：掃描名片上的 QR Code，擷取聯絡資訊。
產線追蹤：每個產品貼上 QR Code，在生產各階段掃描記錄流程。

🎯 結語

QR Code 與 BarCode 辨識是電腦視覺中相對容易上手、卻非常實用的一塊。
搭配 pyzbar 與 OpenCV，幾十行程式就能完成即時掃描系統。

下一篇將進入 OpenCV 專案：即時濾鏡相機，實作一個可即時切換、疊加多種視覺效果的濾鏡相機。

註：以上參考了
OpenCV QRCodeDetector 官方文件
 pyzbar GitHub
qrcode PyPI

Python | OpenCV YOLOv8 常見問題 Q&A

2026-04-11T10:00:00.000Z

📚 前言

在上一篇 YOLOv8 推論與匯出 中，我們完成了整個 YOLOv8 自訓練物件偵測的流程。

走完一遍之後，往往會冒出很多實際操作上的問題。本篇整理成 Q&A 格式，針對最常見的問題逐一解答。

📋 目錄

增加類別‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Q1 — 想新增類別，只訓練新類別資料可以嗎？
Q2 — Fine-tuning 時只放新類別資料就好嗎？
Q3 — 遷移學習 Fine-tuning 的做法？
Q4 — 原本的訓練資料遺失了怎麼辦？
Q5 — 一個類別訓練一個模型，好不好？

資料集

Q6 — 每個類別需要幾張圖？
Q7 — 訓練集和驗證集的比例怎麼分？
Q8 — 圖片一定要先 resize 成 640×640 嗎？
Q9 — 資料增強需要自己處理嗎？

訓練

Q10 — 訓練中斷了，可以繼續接著訓練嗎？
Q11 — 沒有顯卡，用 CPU 訓練可以嗎？
Q12 — yolov8n/s/m/l/x 要選哪個？

效果診斷‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Q13 — mAP 高但實際效果差，為什麼？
Q14 — 某個類別 AP 特別低，怎麼改善？
Q15 — 同一物件被框了好幾個框，怎麼解決？
Q16 — 小物件偵測效果很差，怎麼辦？
Q17 — 目標因遠近變大變小，需要特別處理嗎？

標註與模型資源

Q18 — 可以用遊戲 SPR 圖檔做預標籤模型嗎？
Q19 — 已有訓練好的模型，可以幫新圖片自動產生標籤嗎？
Q20 — 哪裡可以下載別人已訓練好的模型？

❓ Q1：已訓練好 cat/dog 模型，想新增 fish 類別，可以只訓練 fish 的資料直接加進去嗎？

A：不行，因為模型的輸出格式在訓練時就已固定，沒辦法事後加欄位。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

可以把它想成一張印好的表格：cat/dog 模型只有「2 個類別欄位」，要新增 fish 就得改成「3 個類別欄位」——整張表要重印，沒辦法在旁邊貼一欄上去。

面對這個情況，有兩種策略：

策略	是否需要舊資料	推論速度	適用場景
遷移學習 Fine-tuning（推薦）	需要全部	快（單模型）	有舊資料、追求精準
獨立模型 + 合併推論	只需新類別	慢（多模型）	舊資料遺失、模組化需求

❓ Q2：Fine-tuning 時，只放 fish 的資料就好了嗎？

A：不行，模型會「忘掉」cat 和 dog。

這個現象叫做災難性遺忘（Catastrophic Forgetting）：模型只看 fish 資料時，原本辨識 cat/dog 的記憶會被覆蓋，訓練完就只認識 fish 了。

Fine-tuning 時，資料集必須同時包含 cat、dog、fish 三個類別的圖片。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

❓ Q3：遷移學習 Fine-tuning 的做法？

步驟：

準備 fish 的圖片與標籤
把 cat/dog 原有資料與 fish 資料合併
更新 data.yaml，類別順序不能改（cat=0, dog=1 維持不動）
從 best.pt 繼續訓練

# data_v2.yaml
path: .
train: train_v2.txt     # cat + dog + fish 的訓練圖片路徑
val:   val_v2.txt       # cat + dog + fish 的驗證圖片路徑

nc: 3
names: ['cat', 'dog', 'fish']   # 舊順序不能改！新類別接在後面

# finetune_add_class.py
from ultralytics import YOLO

# 類別數改變時，偵測頭會自動重建；主幹（Backbone）特徵保留
model = YOLO("runs/detect/custom_detector/weights/best.pt")

model.train(
    data="data_v2.yaml",
    epochs=100,
    imgsz=640,
    batch=16,
    name="custom_detector_v2",
    lr0=0.001,      # 遷移學習建議用較小的起始學習率
    lrf=0.01,
    patience=20,
)

❓ Q4：原本的 cat/dog 訓練資料遺失了怎麼辦？

A：改用「獨立模型 + 合併推論」，只需準備新類別的資料。

先單獨訓練一個 fish 模型：

# train_fish.py
from ultralytics import YOLO

model = YOLO("yolov8n.pt")
model.train(
    data="data_fish.yaml",   # nc: 1, names: ['fish']
    epochs=100,
    imgsz=640,
    batch=16,
    name="fish_detector",
)

推論時兩個模型各跑一次，手動合併結果：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# inference_merged.py
from ultralytics import YOLO
import cv2

model_cat_dog = YOLO("runs/detect/custom_detector/weights/best.pt")   # cat=0, dog=1
model_fish    = YOLO("runs/detect/fish_detector/weights/best.pt")      # fish=0

CLASS_NAMES = ["cat", "dog", "fish"]

img = cv2.imread("assets/test.jpg")
detections = []

for box in model_cat_dog(img, conf=0.5, verbose=False)[0].boxes:
    cls_id = int(box.cls)           # 0=cat, 1=dog，不需偏移
    detections.append((cls_id, float(box.conf), list(map(int, box.xyxy[0]))))

for box in model_fish(img, conf=0.5, verbose=False)[0].boxes:
    cls_id = int(box.cls) + 2       # fish=0 → 合併表中為 2
    detections.append((cls_id, float(box.conf), list(map(int, box.xyxy[0]))))

for cls_id, conf, (x1, y1, x2, y2) in detections:
    label = f"{CLASS_NAMES[cls_id]}: {conf:.2f}"
    cv2.rectangle(img, (x1, y1), (x2, y2), (0, 255, 0), 2)
    cv2.putText(img, label, (x1, y1 - 8),
                cv2.FONT_HERSHEY_SIMPLEX, 0.6, (0, 255, 0), 2)
    print(label)

cv2.imwrite("output/result_merged.jpg", img)
print("已儲存到 output/result_merged.jpg")

❓ Q5：一個類別訓練一個模型，好不好？

A：可行，但長期維護成本高，不建議作為主力做法。

面向	獨立模型	合併模型（Fine-tuning）
新增類別	只需訓練新類別	需要全部資料重訓
推論速度	慢（N 個模型各跑一次）	快（單次推論）
記憶體用量	高（同時載入多個模型）	低
class index 管理	需手動對齊	自動處理

❓ Q6：每個類別需要幾張圖？有最低門檻嗎？

A：沒有硬性規定，但有個參考範圍。

資料量	效果
< 50 張	容易過擬合，難以泛化
100～300 張	最低門檻，類別簡單時勉強夠用
300～500 張	效果開始穩定
1000 張以上	大多數場景都能有不錯表現

💡 比張數更重要的是「多樣性」：不同場景、不同光線、不同角度各拍 100 張，效果通常優於同一場景拍 1000 張。

❓ Q7：訓練集和驗證集的比例怎麼分？

A：常用 8:2，資料量少時可用 7:3。

資料總量	建議比例
< 500 張	7:3
500～2000 張	8:2（最常用）
> 2000 張	9:1

⚠️ 驗證集的分布要和訓練集相似，不能把所有「困難」的圖全放進驗證集，否則驗證指標會失真。

❓ Q8：圖片一定要先 resize 成 640×640 嗎？

A：不需要，YOLOv8 訓練時會自動處理。

原始圖片可以是任意解析度，框架會自動縮放並補黑邊（letterbox）維持長寬比。若圖片中有很小的目標，可以提高 imgsz=1280 保留更多細節，但訓練速度會變慢。

❓ Q9：資料增強需要自己處理嗎？YOLOv8 有內建嗎？

A：不需要，YOLOv8 訓練時預設開啟多種增強。

增強方式	說明
Mosaic	把 4 張圖拼在一起，增加場景複雜度
隨機縮放、平移、裁切	讓模型看到不同大小和位置的目標
水平翻轉	預設開啟
HSV 色彩抖動	隨機調整色調、飽和度、亮度
Copy-paste	把物件複製貼到其他圖片上

一般不需要自己處理，若想調整強度，可修改訓練參數中的 mosaic、flipud、fliplr 等。

❓ Q10：訓練到一半中斷了（停電、當機），可以繼續接著訓練嗎？

A：可以，用 resume=True 從中斷點繼續。

# resume_training.py
from ultralytics import YOLO

# 用 last.pt（不是 best.pt），記錄了目前訓練進度
model = YOLO("runs/detect/custom_detector/weights/last.pt")
model.train(resume=True)

💡 resume=True 會自動恢復所有訓練設定，不需要重新指定 epochs 或其他參數。

❓ Q11：沒有顯卡，用 CPU 訓練可以嗎？速度差多少？

A：可以執行，但速度非常慢。

CPU 比 GPU 慢 10～50 倍
資料量少（100 張以下）勉強可接受
資料量較大時，建議改用 Google Colab（免費 T4 GPU）

❓ Q12：yolov8n / yolov8s / yolov8m / yolov8l / yolov8x，要選哪個？

A：依速度和精準度的需求取捨。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

模型	推論速度	精準度	實際案例
yolov8n	最快	最低	智慧門鈴偵測人臉、無人機即時避障
yolov8s	快	普通	手機 App 掃描商品、樹莓派動作偵測
yolov8m	中等	良好	安全監控客流分析、遊戲畫面人物／物品／怪物偵測
yolov8l	慢	高	工廠生產線瑕疵檢測、倉庫自動盤點
yolov8x	最慢	最高	衛星影像分析、醫療影像輔助診斷

遊戲畫面偵測落在 yolov8s～yolov8m 之間：

動作 RPG、FPS 等節奏快 → yolov8s（偵測必須跟上畫面）
回合制、策略遊戲等節奏慢 → yolov8m（精準度更重要）

💡 建議先用 yolov8n 或 yolov8s 跑通整個流程，再換較大的模型測試精準度是否有明顯提升。

❓ Q13：mAP 很高，但實際場景測試效果很差，為什麼？

A：通常是訓練資料和實際場景「差太多」造成的。

驗證集圖片太「標準」，但實際有複雜背景、不同光線、奇怪角度
模型過擬合，只記住了訓練資料的特徵
實際場景的目標尺寸或角度從未出現在訓練資料中

解法：把實際場景拍攝的圖片加入訓練集。

❓ Q14：某個類別的 AP 特別低，怎麼改善？

A：先看 confusion_matrix 找出根本原因，再對症下藥。

可能原因	解法
該類別訓練資料太少	補充更多圖片
和其他類別外觀相似，常被誤認	補充更多對比性樣本
標籤品質差（框標歪、標錯）	重新檢查並修正標籤
該類別在畫面中通常很小	參考 Q16

❓ Q15：同一個物件被框了好幾個框（重複偵測），怎麼解決？

A：調低 iou 閾值，讓過濾更積極。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

iou 是兩個框的重疊程度（0 = 完全不重疊，1 = 完全重疊）。預設 iou=0.7 表示「重疊超過 70% 才算重複並過濾」。若重複框明顯，往下調讓過濾條件更寬鬆：

# inference_nms.py
from ultralytics import YOLO

model = YOLO("runs/detect/custom_detector/weights/best.pt")

# iou 調低 → 過濾更積極，重複框減少
results = model("assets/test.jpg", conf=0.5, iou=0.45)

for box in results[0].boxes:
    cls_id = int(box.cls)
    conf   = float(box.conf)
    print(f"{model.names[cls_id]}: {conf:.2f}")

⚠️ 物件本身密集（如人群、排列貨物）時，不要調太低，否則會漏掉真實物件。

❓ Q16：小物件偵測效果很差，怎麼辦？

A：有幾個方向可以嘗試。

方法	說明
提高 `imgsz`	640 → 1280，保留更多細節（訓練更慢、更吃記憶體）
降低 `conf` 閾值	小物件信心度通常較低，試試 `conf=0.3`
補充小物件樣本	訓練集裡沒有小目標的圖，模型根本沒學過怎麼偵測
切片推論（SAHI）	把大圖切成小塊分別推論再合併，適合航拍、監控場景

❓ Q17：目標會因為遠近變大變小，訓練需要特別處理嗎？YOLOv8 怎麼實現的？

A：不需要，YOLOv8 天生就會同時偵測不同大小的目標。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

YOLOv8 在同一次推論中，同時用三個不同的「偵測層」各自負責不同大小的目標：

偵測層	負責偵測	對應場景
細節層	小物件	遠距離目標、畫面中的小物件
中間層	中型物件	一般距離目標
全局層	大物件	近距離目標

三層同時運作，不論目標遠近大小，都有對應的層負責，不需要做任何特別處理。

💡 唯一要注意：訓練資料中要有遠中近各種距離的樣本，確保三層都有學習機會。若遠距效果差，通常是遠距樣本太少，補充即可。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

❓ Q18：可以用遊戲的 SPR 圖檔先訓練預標籤模型，再拿來自動標記遊戲截圖嗎？

A：可以，這是有效的兩階段標註策略。

階段	做什麼
① 訓練預標籤模型	用 SPR 圖訓練一個粗糙的偵測器
② 自動標記截圖	用預標籤模型對遊戲截圖做自動框選
③ 人工校正	用 LabelImg 檢查並修正框選結果
④ 訓練最終模型	用校正後的截圖訓練正式模型

讓預標籤更準的技巧：SPR 圖通常是透明或純色背景，可以先把 SPR 圖合成到遊戲背景截圖上再訓練，讓模型提前學會在複雜背景中辨識目標。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

2D 遊戲：SPR 和遊戲畫面幾乎一致，效果最好
3D 遊戲：有光影和透視差異，準確率較低，但仍比從頭手標省力
無論哪種，校正步驟不能省略

❓ Q19：我已經有一個訓練好的模型，可以直接用它來幫新圖片產生標籤嗎？

A：可以，而且比 Q18 的 SPR 方式更準。

讓模型對新圖片推論，把結果輸出成 YOLO 格式的 .txt 標籤檔，再用 LabelImg 校正即可。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# pre_label.py
from ultralytics import YOLO
import os

model     = YOLO("runs/detect/custom_detector/weights/best.pt")
img_dir   = "assets/new_images/"
label_dir = "assets/new_labels/"
os.makedirs(label_dir, exist_ok=True)

for img_file in os.listdir(img_dir):
    if not img_file.lower().endswith((".jpg", ".png")):
        continue

    results = model(os.path.join(img_dir, img_file), conf=0.3)  # conf 低一點，寧可多框也不漏框
    result  = results[0]

    label_path = os.path.join(label_dir, os.path.splitext(img_file)[0] + ".txt")
    with open(label_path, "w") as f:
        for box in result.boxes:
            cls_id        = int(box.cls)
            cx, cy, bw, bh = box.xywhn[0].tolist()   # 歸一化的中心座標 + 寬高
            f.write(f"{cls_id} {cx:.6f} {cy:.6f} {bw:.6f} {bh:.6f}\n")

    print(f"{img_file}：{len(result.boxes)} 個框 → {label_path}")

print("完成！請用 LabelImg 開啟資料夾校正。")

conf=0.3：寧可多框（刪框快）也不漏框（補框慢）
校正完加回訓練集重新訓練，下一輪預標籤會更準，工作量越來越少（這就是 Active Learning）

❓ Q20：有哪些地方可以下載別人已經訓練好的模型？遊戲的也有嗎？

A：有幾個主要平台，遊戲相關的模型在社群平台上也找得到。

平台	特色	適合找什麼
Roboflow Universe	最大的公開模型與資料集社群，可直接下載權重	遊戲偵測模型、各種自訂類別
Ultralytics Hub	YOLOv8 官方平台，品質較有保障	官方範例與社群分享模型
Hugging Face	大型 AI 模型託管平台，搜尋 `yolov8`	各種領域的 YOLOv8 模型
GitHub	搜尋 `yolov8 + 遊戲名稱`（如 `yolov8 minecraft`）	針對特定遊戲的個人專案

找遊戲模型的搜尋建議：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Roboflow Universe：直接搜尋遊戲名稱，如 league of legends、minecraft、genshin
GitHub：搜尋 yolov8 [遊戲名] detection

下載後先確認：

# 載入別人的模型，先查看它認識哪些類別
from ultralytics import YOLO
model = YOLO("下載的模型.pt")
print(model.names)

⚠️ 使用前注意：
確認類別名稱：用 model.names 查看這個模型認識哪些類別
確認授權條款：部分模型有使用限制，商業使用前需確認 License
品質不保證：社群模型品質參差不齊，用於預標籤前建議先測幾張圖

🎯 結語

遇到問題時，通常可以先從資料下手——是否夠多、夠多樣、標籤是否正確。大多數時候，資料品質才是影響模型表現的關鍵。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

下一篇進入新章節 Python | OpenCV QR Code 與 BarCode 辨識，開始 08.專案實作篇的內容。

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
Ultralytics YOLOv8 官方文件 — Train
Ultralytics YOLOv8 官方文件 — Transfer Learning
Ultralytics YOLOv8 官方文件 — Tips for Best Training Results
Catastrophic Forgetting — Wikipedia‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Python | OpenCV YOLOv8 推論與匯出

2026-04-11T01:00:00.000Z

📚 前言

在上一篇 YOLOv8 訓練結果分析 中，我們確認了模型的訓練品質。
恭喜你！已經完成從資料集準備、預標籤、訓練，到結果分析的完整流程。

現在來到最後一步 —— 把訓練好的模型實際應用起來。

這一篇會教你：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

如何對單張圖片、影片、即時攝影機進行推論
如何自訂繪製偵測結果
如何把模型匯出成 ONNX 格式（方便後續與 OpenCV 深度整合）

本篇所有範例都會用到前一篇訓練好的最佳模型：

1	runs/detect/custom_detector/weights/best.pt

若檔案不存在，請先確認 YOLOv8 訓練進階設定 的 train_full.py 是否正常跑完。

🎨 範例圖片與影片

圖片‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

來源：Cat Image。
下載後將檔名改為 test_cat.jpg，放在 assets/，即可用於以下各範例。

影片

來源：Cat And Dogs Video。
下載後將檔名改為 test_cat_and_dog.mp4，放在 assets/，即可用於影片推論範例。

💻 靜態圖片推論

說明：
conf=0.5 是信心度門檻，建議從 0.5 開始調整，太低會有很多誤報，太高會漏掉物件。

# inference_image.py
from ultralytics import YOLO
import cv2

model = YOLO("runs/detect/custom_detector/weights/best.pt")

# 推論
results = model("assets/test_cat.jpg", conf=0.5, save=False)

# 取得第一張結果（單張圖片通常只有一個）
result = results[0]

# 印出偵測資訊
for box in result.boxes:
    cls_id = int(box.cls)
    conf = float(box.conf)
    x1, y1, x2, y2 = map(int, box.xyxy[0])
    label = f"{model.names[cls_id]}: {conf:.2f}"
    print(f"偵測到：{label}，座標：({x1},{y1}) - ({x2},{y2})")

# ========== 顯示圖片（推薦寫法） ==========
img = result.plot()                    # 產生帶框的圖片 (BGR格式)
cv2.imshow("YOLOv8 Detection", img)    # 自訂視窗名稱
cv2.waitKey(0)                         # 按任意鍵關閉視窗
cv2.destroyAllWindows()                # 關閉所有 OpenCV 視窗

# 儲存結果
result.save(filename="output/result.jpg")
print("已儲存到 output/result.jpg")

圖：載入訓練好的 YOLOv8 模型對靜態圖片推論，取得邊界框座標、類別與信心度並儲存結果‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

💻 批次圖片推論

# inference_batch.py
from ultralytics import YOLO
import os

model   = YOLO("runs/detect/custom_detector/weights/best.pt")
img_dir = "assets/"
out_dir = "output/"                         # 輸出目錄：output/
os.makedirs(out_dir, exist_ok=True)

image_paths = [os.path.join(img_dir, f)
               for f in os.listdir(img_dir)
               if f.lower().endswith((".jpg", ".png"))]

results = model(image_paths, conf=0.5, batch=8)

for i, r in enumerate(results):
    print(f"\n圖片 {image_paths[i]}：")
    for box in r.boxes:
        cls_id = int(box.cls)
        conf   = float(box.conf)
        print(f"  {model.names[cls_id]}: {conf:.2f}")

    fname = os.path.basename(image_paths[i])
    r.save(filename=os.path.join(out_dir, fname))  # 保留原檔名，存入 output/

print(f"\n完成：結果儲存至 {out_dir}")

圖：批次讀取目錄中的所有圖片一次送入模型推論，輸出各圖片的偵測類別並儲存標註結果

💻 影片推論

# inference_video.py
from ultralytics import YOLO

model = YOLO("runs/detect/custom_detector/weights/best.pt")

# 對影片推論，結果自動儲存
results = model(
    "assets/test_cat_and_dog.mp4",
    conf=0.5,
    save=True,          # 儲存標註後的影片，預設輸出在 runs/detect/predict/
)

圖：對影片檔案執行 YOLOv8 推論，自動儲存標註後的輸出影片

💻 即時攝影機推論

# inference_camera.py
from ultralytics import YOLO
import cv2

model = YOLO("runs/detect/custom_detector/weights/best.pt")

cap = cv2.VideoCapture(0)
print("按 q 離開")

while True:
    ret, frame = cap.read()
    if not ret:
        break

    results = model(frame, conf=0.5, verbose=False)
    annotated = results[0].plot()

    cv2.imshow("YOLOv8 Detection", annotated)

    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

📝 註：由於本身沒有攝影鏡頭，所以無法示範效果。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

💻 手動繪製偵測結果（自訂樣式）

若需要自訂邊界框顏色或字型，可不使用 .plot() 而自行繪製：

# inference_camera_custom.py
from ultralytics import YOLO
import cv2

model = YOLO("runs/detect/custom_detector/weights/best.pt")

COLORS = [(0,255,0), (255,0,0), (0,0,255), (255,255,0)]  # 每個類別一個顏色

cap = cv2.VideoCapture(0)

while True:
    ret, frame = cap.read()
    if not ret:
        break

    results = model(frame, conf=0.5, verbose=False)

    for box in results[0].boxes:
        cls_id      = int(box.cls)
        conf        = float(box.conf)
        x1,y1,x2,y2 = map(int, box.xyxy[0])
        color       = COLORS[cls_id % len(COLORS)]
        label       = f"{model.names[cls_id]} {conf:.2f}"

        cv2.rectangle(frame, (x1, y1), (x2, y2), color, 2)
        cv2.putText(frame, label, (x1, y1 - 8),
                    cv2.FONT_HERSHEY_SIMPLEX, 0.6, color, 2)

    cv2.imshow("YOLOv8", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

📝 註：由於本身沒有攝影鏡頭，所以無法示範效果。

💻 匯出為 ONNX

匯出 ONNX 後可用 cv2.dnn 或 onnxruntime 推論，不依賴 ultralytics：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# export_onnx.py
from ultralytics import YOLO

model = YOLO("runs/detect/custom_detector/weights/best.pt")

# 匯出為 ONNX
model.export(format="onnx", imgsz=640, dynamic=False, simplify=True)
# 匯出後產生：runs/detect/custom_detector/weights/best.onnx

圖：將訓練好的 YOLOv8 模型匯出為 ONNX 格式，供跨平台部署使用

使用 onnxruntime 推論：

# inference_onnx.py
import onnxruntime as ort
import numpy as np
import cv2

session    = ort.InferenceSession("runs/detect/custom_detector/weights/best.onnx")
input_name = session.get_inputs()[0].name

def preprocess(img, imgsz=640):
    img_rgb   = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
    img_rsz   = cv2.resize(img_rgb, (imgsz, imgsz))
    blob      = img_rsz.astype(np.float32) / 255.0
    return np.expand_dims(blob.transpose(2, 0, 1), axis=0)

img  = cv2.imread("assets/test_cat.jpg")
blob = preprocess(img)

outputs = session.run(None, {input_name: blob})
print(f"輸出形狀：{outputs[0].shape}")
# 輸出形狀為 (1, 6, 8400)
# 意義說明：
#   - 第一維 1     → batch size
#   - 第二維 6     → 每個候選框包含的資訊數量
#                    = 4（邊界框：x_center, y_center, width, height） 
#                    + 1（objectness / confidence） 
#                    + 1（你的自訂類別數，目前應該是 2 類：cat 和 dog？）
#   - 第三維 8400  → 候選框總數量（YOLOv8 在 640x640 輸入時通常為 8400）
#
# 注意：
#   YOLOv8 的 ONNX 輸出格式與 YOLOv5 不同，已經把 class confidence 與 objectness 合併處理。
#   你必須自行實作：
#   1. 過濾低信心度
#   2. 還原座標 (從 center+wh → xyxy)
#   3. Non-Maximum Suppression (NMS)

圖：使用 onnxruntime 載入 ONNX 模型，對圖片進行前處理並執行推論取得原始輸出張量‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

💡 ONNX 輸出的後處理（NMS、座標還原）較複雜，實際部署建議直接使用 ultralytics 的 Python API，或使用 cv2.dnn.readNetFromONNX 搭配 YOLOv8 的後處理邏輯。

💻 其他匯出格式

各格式有平台限制，請依環境選擇：

格式	需求	適用場景
`engine`（TensorRT）	NVIDIA GPU + TensorRT 安裝	伺服器端高速推論
`coreml`	macOS 環境	iPhone / iPad 部署
`tflite`	無特殊需求	Android / 嵌入式裝置

⚠️ 注意事項

conf 閾值的設定：預設為 0.25，太低會有很多誤報，太高會漏掉低信心的正確偵測，需根據應用場景調整。
iou 閾值（NMS）：預設為 0.7，控制重疊邊界框的過濾，物件密集的場景建議調低（如 0.5）。
verbose=False：在即時推論的迴圈中必須設定，否則每幀都會輸出推論資訊，嚴重影響效能。
ONNX 的後處理：YOLOv8 的 ONNX 輸出格式在不同版本間可能略有差異，建議以 ultralytics 的 Python API 為主，ONNX 用於需要脫離 Python 環境的部署場景。

📊 應用場景

工廠自動品管：用訓練好的瑕疵偵測模型，對生產線即時攝影機畫面進行偵測。
倉庫商品辨識：偵測並定位貨架上的商品，輔助自動化盤點。
安全監控：偵測特定人員或行為，即時發出警報。

🎯 結語

至此，完整的 YOLOv8 自訓練物件偵測流程全部走完：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

環境安裝 → 資料集準備 → 模型訓練 → 結果分析 → 推論與匯出

掌握這個流程，就能針對任何你想偵測的物件，從零開始訓練出專屬的 YOLOv8 模型。

下一篇是 YOLOv8 常見問題 Q&A，整理學完整個流程後最常遇到的問題，包含增加新類別、遷移學習策略與獨立模型的優缺點。

註：以上參考了
Ultralytics YOLOv8 官方文件 — Predict
Ultralytics YOLOv8 官方文件 — Export
Ultralytics YOLOv8 官方文件 — Python Usage
ONNX Runtime 官方文件

Python | OpenCV YOLOv8 訓練結果分析

2026-04-10T01:00:00.000Z

📚 前言

在上一篇 YOLOv8 訓練進階設定 中，我們完成了模型訓練。
這一篇介紹如何 解讀訓練結果，判斷模型是否訓練良好，以及找出需要改進的方向。

YOLOv8 在訓練結束後會自動產生大量的圖表和檔案。學會看懂這些資訊，你才能知道：

模型目前表現如何？
是否有過擬合？
哪個類別學得不好？
還需要繼續訓練還是需要補資料？

🗃️ 訓練結果目錄結構

前一篇 train_full.py 跑完後，結果儲存在 runs/detect/custom_detector/（對應 name="custom_detector"）。若目錄不存在，請先確認訓練是否正常跑完。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

runs/detect/custom_detector/
├── weights/
│   ├── best.pt                      ← 驗證 mAP 最高的模型（用於部署）
│   ├── last.pt                      ← 最後一個 epoch 的模型（用於繼續訓練）
│   └── epoch*.pt                    ← 中間訓練過程的權重（可刪除以節省空間）
├── results.csv                      ← 每個 epoch 的詳細數值（loss、mAP 等）
├── results.png                      ← 訓練曲線圖（Loss + Metrics）
├── confusion_matrix.png             ← 混淆矩陣
├── confusion_matrix_normalized.png
├── BoxPR_curve.png                  ← Box Precision-Recall 曲線
├── BoxF1_curve.png                  ← Box F1-Confidence 曲線
├── BoxP_curve.png                   ← Box Precision-Confidence 曲線
├── BoxR_curve.png                   ← Box Recall-Confidence 曲線
├── val_batch0_labels.jpg            ← 驗證集真實標籤視覺化
├── val_batch0_pred.jpg              ← 驗證集模型預測視覺化
├── labels.jpg                       ← 其他標籤圖（通常是訓練或額外視覺化）
├── train_batch0.jpg                 ← 訓練批次圖（可選保留）
├── train_batch1.jpg
├── train_batch2.jpg
└── args.yaml                        ← 本次訓練使用的所有超參數

最需要關注的三個檔案：

best.pt → 拿來部署的模型
results.png → 一眼看懂訓練趨勢
confusion_matrix.png → 看哪個類別容易搞錯

💡 best.pt 是部署時使用的模型，不要用 last.pt 做推論，因為最後一個 epoch 不一定是最好的。

🔎 Loss 曲線怎麼看？（results.png）

results.png 中包含三種 Loss 的訓練與驗證曲線：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Loss 名稱	說明
`box_loss`	邊界框座標的回歸損失，越低代表邊界框越準
`cls_loss`	類別分類損失，越低代表類別辨識越準
`dfl_loss`	Distribution Focal Loss，邊界框分布損失（YOLOv8 特有）

正常的訓練曲線應該是：

train/box_loss、train/cls_loss、train/dfl_loss 持續穩定下降
val/box_loss、val/cls_loss、val/dfl_loss 同步下降，並趨於平穩

異常情況判斷：

現象	可能原因	解法
train loss 下降但 val loss 上升	過擬合	增加資料、提高 `weight_decay`、降低 `epochs`
train/val loss 都不下降	學習率太小或資料有問題	提高 `lr0`，重新確認標籤格式
Loss 震盪劇烈	學習率太大或 `batch` 太小	降低 `lr0`，增加 `batch`
Loss 為 NaN	標籤座標超出 0~1 範圍	重新確認標籤格式

圖：results.png 訓練曲線圖，包含各項 Loss 與 mAP 指標的每個 epoch 變化‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🔎 mAP 指標怎麼看？

mAP（mean Average Precision）是物件偵測最重要的評估指標，有三個地方可以看到：

訓練時的終端機輸出：每個 epoch 結束後會印出當前的 mAP50 與 mAP50-95
results.png：訓練結束後自動產生，包含完整的 mAP 曲線圖，在 runs/detect/custom_detector/ 下
results.csv：每個 epoch 的詳細數值，可用程式讀取（見本篇下方的範例）

各指標的意義：

指標	說明
`mAP50`	IoU 閾值 = 0.5 時的 mAP，只要邊界框重疊超過 50% 就算正確，是最常用的指標
`mAP50-95`	IoU 閾值從 0.5 到 0.95 的平均 mAP，要求更嚴格的邊界框定位精度，通常比 mAP50 低很多
`Precision`	模型預測出的框中，有多少比例是真的有物件（誤報率低）
`Recall`	實際存在的物件中，有多少比例被模型找到了（漏報率低）

mAP50 一般參考標準：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

mAP50 範圍	評估等級
< 0.40	較差，需要大幅改善資料或標註
0.40 ~ 0.60	普通，可以接受但還有進步空間
0.60 ~ 0.75	良好
> 0.75	優秀

💡 自訂資料集的 mAP 沒有絕對標準，最重要的是「是否滿足應用需求」。例如安全監控對 Recall 要求高（不能漏報），商品辨識則對 Precision 要求高（不能誤報）。

圖：終端機輸出、results.png、results.csv，包含各項 Loss 與 mAP 指標的每個 epoch 變化

🔎 混淆矩陣怎麼看？

YOLOv8 會產生兩張混淆矩陣圖：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

confusion_matrix.png：顯示實際的預測數量
confusion_matrix_normalized.png：推薦查看（每個類別的預測比例，0~1）

重點看 confusion_matrix_normalized.png：

對角線顏色越深（接近 1.0）：該類別辨識越準確
非對角線有明顯顏色：模型常把 A 類別誤認為 B 類別（這就是最需要改進的地方）
background 那一行/列：
- 右邊的 background FP：模型誤檢（把背景當成物件）
- 下方的 background FN：模型漏檢（沒找到實際存在的物件）

看這張圖可以快速找出「哪個類別最容易搞錯」，然後針對性地補充該類別的資料或改善標註品質。

圖：confusion_matrix_normalized.png 範例，對角線顏色越接近 1.0 代表該類別分類越準確，非對角線的顏色代表容易混淆的類別‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

💻 用程式讀取訓練結果

本節需要額外安裝 pandas 與 matplotlib：

1	pip install pandas matplotlib

# analyze_results.py
import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv("runs/detect/custom_detector/results.csv")
df.columns = df.columns.str.strip()   # 去除欄位名稱的空白

print(df.columns.tolist())            # 查看所有欄位名稱
print(df.tail(5))                     # 查看最後 5 個 epoch 的數值

# 找出最佳 epoch
best_epoch = df["metrics/mAP50(B)"].idxmax()
print(f"\n最佳 epoch：{best_epoch + 1}")
print(f"最佳 mAP50：{df['metrics/mAP50(B)'].max():.4f}")
print(f"最佳 mAP50-95：{df['metrics/mAP50-95(B)'].max():.4f}")

# 繪製 mAP 曲線
plt.figure(figsize=(10, 4))
plt.plot(df["metrics/mAP50(B)"],    label="mAP50")
plt.plot(df["metrics/mAP50-95(B)"], label="mAP50-95")
plt.xlabel("Epoch")
plt.ylabel("mAP")
plt.legend()
plt.title("mAP Training Curve")
plt.savefig("mAP_curve.png")
plt.show()

圖：讀取 results.csv 找出最佳 epoch 並繪製 mAP50 與 mAP50-95 的訓練曲線圖

💻 執行驗證取得詳細報告

訓練完成後，可單獨對驗證集執行評估取得更詳細的結果：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# evaluate.py
import torch
from ultralytics import YOLO
import multiprocessing   # 加上這行

if __name__ == '__main__':
    # 解決 Windows multiprocessing 錯誤
    multiprocessing.freeze_support()

    # 載入模型
    model = YOLO("runs/detect/custom_detector/weights/best.pt")

    # 執行驗證（強制關閉多進程，避免 Windows 問題）
    metrics = model.val(
        data="data.yaml",
        device=0 if torch.cuda.is_available() else "cpu",
        workers=0,           # ← 關鍵！設成 0 比較穩定
        batch=16,            # 可根據你的顯卡調整（太大也會出問題）
        imgsz=640,           # 如果你訓練時用其他尺寸，可以指定
        plots=True           # 想產生 confusion_matrix 等圖片就開啟
    )

    # 印出指標
    print(f"mAP50：    {metrics.box.map50:.4f}")
    print(f"mAP50-95： {metrics.box.map:.4f}")
    print(f"Precision：{metrics.box.mp:.4f}")
    print(f"Recall：   {metrics.box.mr:.4f}")

    print("\n各類別 AP50：")
    for i, (name, ap) in enumerate(zip(metrics.names.values(), metrics.box.ap50)):
        print(f"  {name}: {ap:.4f}")

圖：載入最佳模型對驗證集執行評估，輸出 mAP50、mAP50-95、Precision、Recall 及各類別 AP50

🔎 val_batch 視覺化

val_batch0_labels.jpg 與 val_batch0_pred.jpg 是驗證集第一批次的對照圖：

Labels：實際標註的邊界框
Pred：模型預測的邊界框

直接比較這兩張圖，能快速判斷模型的偵測品質與定位精度。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

💡 本範例說明：這裡使用的標籤是以預標籤（Pre-labeling）方式自動生成，並未使用 LabelImg 逐一手動修正，因此 Labels 圖中可以看到部分標記有誤（例如邊界框位置不準或類別標錯）。這也說明了標註品質對訓練結果的影響——如果 Labels 本身就有錯，模型學到的也會是錯誤的邊界框位置，進而拉低 mAP。

圖：val_batch0_labels.jpg — 驗證集實際標註的邊界框（因使用預標籤且未手動修正，部分標記有誤）

圖：val_batch0_pred.jpg — 模型預測的邊界框，與上圖對照判斷偵測品質‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

⚠️ 注意事項

mAP 低不一定代表模型差：如果資料量少、類別困難、或標註品質差，mAP 自然偏低，先確認資料品質。
best.pt 與 last.pt 的差異：best.pt 是 mAP 最高的 epoch，不一定是最後一個 epoch。建議以 best.pt 部署。
Early Stopping 後的 last.pt：若訓練因 Early Stopping 提早結束，last.pt 是停止時的狀態，不一定是最好的，還是要用 best.pt。

🎯 結語

學會解讀訓練結果，才能有效判斷模型是否需要更多資料、更長訓練時間，或調整超參數。
下一步是 YOLOv8 推論與匯出，把訓練好的模型實際應用在圖片、影片或即時攝影機上。

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
Ultralytics YOLOv8 官方文件 — Val
Ultralytics YOLOv8 官方文件 — Train
Mean Average Precision — 物件偵測評估指標說明‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Python | OpenCV YOLOv8 訓練進階設定

2026-04-09T10:00:00.000Z

📚 前言

在上一篇 YOLOv8 模型訓練 中，我們完成了基本的訓練流程設定。

但「能訓練」和「訓練得好」是兩回事。

這一篇將介紹兩個非常重要的進階主題：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

資料增強：讓模型看到更多變化，幫助它學得更好
防止過擬合：避免模型死背訓練資料，真正具備泛化能力

掌握這些設定後，你的模型訓練效果會明顯提升。

💻 內建資料增強設定

YOLOv8 在訓練時內建了豐富的資料增強，預設已自動啟用，不需要額外撰寫增強程式碼。
一般情況下預設值已夠用，不需要動。但以下幾種情況可能需要調整：

資料集很小（< 100 張）：可以加強增強強度，讓模型看到更多變化，減少過擬合
物件方向固定（如俯視圖）：可以關閉 fliplr、flipud，避免產生現實中不存在的翻轉角度
室內固定光源場景：hsv_s、hsv_v 可以調低，不需要大幅模擬色彩變化
訓練結果不穩定或 mAP 很低：可以嘗試設 mosaic=0.0，有時過強的增強反而干擾學習

可透過參數調整增強強度：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# augmentation_params.py
import torch
from ultralytics import YOLO

model = YOLO("yolov8n.pt")

model.train(
    data="data.yaml",
    epochs=100,
    device=0 if torch.cuda.is_available() else "cpu",
    # 幾何增強
    fliplr=0.5,       # 水平翻轉機率（預設 0.5）
    flipud=0.0,       # 垂直翻轉機率（預設 0.0，通常不需要）
    degrees=0.0,      # 旋轉角度範圍 ±degrees
    translate=0.1,    # 平移比例
    scale=0.5,        # 縮放範圍（0.5 表示 0.5x ~ 1.5x）
    shear=0.0,        # 剪切角度
    perspective=0.0,  # 透視變換
    # 色彩增強
    hsv_h=0.015,      # 色相抖動
    hsv_s=0.7,        # 飽和度抖動
    hsv_v=0.4,        # 明度抖動
    # 進階增強
    mosaic=1.0,       # Mosaic 增強（將 4 張圖拼成 1 張，1.0 = 100% 啟用）
    mixup=0.0,        # MixUp 增強機率
    copy_paste=0.0,   # Copy-Paste 增強機率
)

💡 Mosaic 增強是 YOLO 的招牌技術，將 4 張圖片拼接在一起，讓模型學習更多背景多樣性，對偵測小物件特別有效。

💻 防止過擬合設定

過擬合是指模型在訓練集表現很好，但在驗證集表現變差。

YOLOv8 提供了以下常見防過擬合機制‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# anti_overfit_example.py
import torch
from ultralytics import YOLO

model = YOLO("yolov8n.pt")

model.train(
    data="data.yaml",
    epochs=150,
    imgsz=640,
    batch=16,
    device=0 if torch.cuda.is_available() else "cpu",
    
    # === 防過擬合核心參數 ===
    patience=30,           # 連續 30 個 epoch 驗證指標沒改善就自動停止（Early Stopping）
    weight_decay=0.0005,   # L2 正規化，防止權重過大
    dropout=0.0,           # Dropout（過擬合嚴重時可試 0.1 ~ 0.3）
    
    # 其他常用設定
    lr0=0.01,              # 初始學習率
    lrf=0.01,              # 最終學習率比例
)

💡 如何判斷是否過擬合、怎麼讀懂訓練曲線，將在 YOLOv8 訓練結果分析 中完整說明。

💻 完整訓練範例

整合基本參數、資料增強與防過擬合設定：

# train_full.py
import time
import torch
from ultralytics import YOLO

print(f"使用裝置：{'GPU - ' + torch.cuda.get_device_name(0) if torch.cuda.is_available() else 'CPU'}")

model = YOLO("yolov8s.pt")

start = time.time()

model.train(
    data="data.yaml",
    epochs=120,
    imgsz=640,
    batch=16,
    device=0 if torch.cuda.is_available() else "cpu",
    workers=0,                    # Windows 必須設 0
    name="custom_detector",
    
    # 防過擬合
    patience=30,
    weight_decay=0.0005,
    
    # 資料增強
    mosaic=1.0,
    fliplr=0.5,
    hsv_h=0.015,
    hsv_s=0.7,
    hsv_v=0.4,
    
    # 其他實用設定
    save_period=10,               # 每 10 個 epoch 存一次
    plots=True,                   # 產生訓練曲線圖
    verbose=True
)

elapsed = time.time() - start
print(f"訓練完成，總耗時：{elapsed // 3600:.0f} 時 {elapsed % 3600 // 60:.0f} 分 {elapsed % 60:.0f} 秒")
print("最佳模型：runs/detect/custom_detector/weights/best.pt")

圖：完整訓練範例，整合資料增強、Early Stopping、定期儲存等設定並輸出最佳模型路徑‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

⚠️ 注意事項

patience 不要設太小：YOLOv8 訓練初期的 mAP 可能波動較大，patience=10 可能會太早停止。建議至少設 20~30。
增強設定需配合資料集特性：並非增強越強越好，過強的增強（例如對方向固定的物件開啟翻轉）反而會讓模型學到錯誤的模式。
先用小 epochs 測試：正式訓練前，建議先用 epochs=10 跑一次，確認參數設定合理後再調高。

🎯 結語

資料增強與防過擬合是讓模型從「能跑」進化到「訓練得好」的關鍵設定。
適當調整這些參數，能讓你的模型在資料量有限的情況下，仍然獲得不錯的泛化能力。
下一步是 YOLOv8 訓練結果分析，學習如何看懂訓練過程產生的各種圖表與指標，判斷模型是否真的學好了。

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
Ultralytics YOLOv8 官方文件 — Train
Ultralytics YOLOv8 官方文件 — Configuration
Ultralytics YOLOv8 官方文件 — Augmentation‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Python | OpenCV YOLOv8 模型訓練

2026-04-09T01:00:00.000Z

📚 前言

在上一篇 YOLOv8 預標籤（Pre-Label） 中，我們用預訓練模型自動產生標籤草稿，再透過 LabelImg 人工修正，完成了標記工作。
這一篇進入最核心的環節：YOLOv8 模型訓練。

YOLOv8 的訓練指令非常簡潔，但背後有許多重要參數影響訓練效果。
這一篇說明每個關鍵參數的意義，以及 GPU 加速與中斷恢復的設定方式。

🔎 開始訓練前的確認

在開始訓練之前，請確認前幾篇的工作都已完成，你手上應該有以下結構：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

project/
├── raw_images/          ← 原始圖片（20260407 收集）
├── raw_labels/          ← 預標籤 + 人工修正後的 .txt（20260408 完成）
├── dataset/
│   ├── images/
│   │   ├── train/       ← 訓練集圖片
│   │   └── val/         ← 驗證集圖片
│   └── labels/
│       ├── train/       ← 訓練集標籤
│       └── val/         ← 驗證集標籤
├── data.yaml            ← 訓練用設定檔（20260407 建立）
└── train.py             ← 本篇將撰寫此檔案

💻 基本訓練指令

🔹 指令列方式

yolo detect train \
  model=yolov8n.pt \
  data=data.yaml \
  epochs=100 \
  imgsz=640 \
  batch=16 \
  device=0         # 無 GPU 請改為 device=cpu

🔹 Python API 方式

# train.py
import time
import torch
from ultralytics import YOLO

model = YOLO("yolov8n.pt")  # 以預訓練模型為起點（第一次執行會自動下載）

start = time.time()

results = model.train(
    data="data.yaml",                                  # 資料集設定檔路徑（由 20260407 的 create_yaml.py 產生）
    epochs=100,                                        # 訓練總輪數，初次建議先設 3~5 確認流程
    imgsz=640,                                         # 輸入圖片尺寸，越大越準確但越慢、越吃記憶體
    batch=16,                                          # 每批次圖片數，GPU 記憶體不足時調小（8、4）
    device=0 if torch.cuda.is_available() else "cpu",  # 自動偵測 GPU，無 GPU 退回 CPU
    workers=0,                                         # 資料載入執行緒數，Windows 必須設 0
    name="my_model",                                   # 訓練結果子目錄，結果存在 runs/detect/my_model/
    save_period=10,                                    # 每 10 個 epoch 儲存一次 checkpoint
    plots=True,                                        # 自動產生訓練曲線圖表
    verbose=True,                                      # 顯示每個 epoch 的詳細訓練資訊
)

elapsed = time.time() - start
print(f"訓練完成，總耗時：{elapsed // 3600:.0f} 時 {elapsed % 3600 // 60:.0f} 分 {elapsed % 60:.0f} 秒")

D:\PythonWorkspace\yolov8-tutorial\.venv\Scripts\python.exe D:\PythonWorkspace\yolov8-tutorial\train.py 
Ultralytics 8.4.37  Python-3.10.11 torch-2.11.0+cu130 CUDA:0 (NVIDIA GeForce RTX 2060 SUPER, 8192MiB)
engine\trainer: agnostic_nms=False, amp=True, angle=1.0, augment=False, auto_augment=randaugment, batch=16, 
bgr=0.0, box=7.5, cache=False, cfg=None, classes=None, close_mosaic=10, cls=0.5, cls_pw=0.0, compile=False, 
conf=None, copy_paste=0.0, copy_paste_mode=flip, cos_lr=False, cutmix=0.0, data=data.yaml, degrees=0.0, 
deterministic=True, device=0, dfl=1.5, dnn=False, dropout=0.0, dynamic=False, embed=None, end2end=None, 
epochs=100, erasing=0.4, exist_ok=False, fliplr=0.5, flipud=0.0, format=torchscript, fraction=1.0, 
freeze=None, half=False, hsv_h=0.015, hsv_s=0.7, hsv_v=0.4, imgsz=640, int8=False, iou=0.7, keras=False, 
kobj=1.0, line_width=None, lr0=0.01, lrf=0.01, mask_ratio=4, max_det=300, mixup=0.0, mode=train, 
model=yolov8n.pt, momentum=0.937, mosaic=1.0, multi_scale=0.0, name=my_model, nbs=64, nms=False, 
opset=None, optimize=False, optimizer=auto, overlap_mask=True, patience=100, perspective=0.0, plots=True, 
pose=12.0, pretrained=True, profile=False, project=None, rect=False, resume=False, retina_masks=False, 
rle=1.0, save=True, save_conf=False, save_crop=False, save_dir=D:\PythonWorkspace\yolov8-tutorial\runs\detect\my_model, 
save_frames=False, save_json=False, save_period=10, save_txt=False, scale=0.5, seed=0, shear=0.0, show=False, 
show_boxes=True, show_conf=True, show_labels=True, simplify=True, single_cls=False, source=None, split=val, 
stream_buffer=False, task=detect, time=None, tracker=botsort.yaml, translate=0.1, val=True, verbose=True, 
vid_stride=1, visualize=False, warmup_bias_lr=0.1, warmup_epochs=3.0, warmup_momentum=0.8, weight_decay=0.0005, 
workers=0, workspace=None
Overriding model.yaml nc=80 with nc=2

                   from  n    params  module                                       arguments                     
  0                  -1  1       464  ultralytics.nn.modules.conv.Conv             [3, 16, 3, 2]                 
  1                  -1  1      4672  ultralytics.nn.modules.conv.Conv             [16, 32, 3, 2]                
  2                  -1  1      7360  ultralytics.nn.modules.block.C2f             [32, 32, 1, True]             
  3                  -1  1     18560  ultralytics.nn.modules.conv.Conv             [32, 64, 3, 2]                
  4                  -1  2     49664  ultralytics.nn.modules.block.C2f             [64, 64, 2, True]             
  5                  -1  1     73984  ultralytics.nn.modules.conv.Conv             [64, 128, 3, 2]               
  6                  -1  2    197632  ultralytics.nn.modules.block.C2f             [128, 128, 2, True]           
  7                  -1  1    295424  ultralytics.nn.modules.conv.Conv             [128, 256, 3, 2]              
  8                  -1  1    460288  ultralytics.nn.modules.block.C2f             [256, 256, 1, True]           
  9                  -1  1    164608  ultralytics.nn.modules.block.SPPF            [256, 256, 5]                 
 10                  -1  1         0  torch.nn.modules.upsampling.Upsample         [None, 2, 'nearest']          
 11             [-1, 6]  1         0  ultralytics.nn.modules.conv.Concat           [1]                           
 12                  -1  1    148224  ultralytics.nn.modules.block.C2f             [384, 128, 1]                 
 13                  -1  1         0  torch.nn.modules.upsampling.Upsample         [None, 2, 'nearest']          
 14             [-1, 4]  1         0  ultralytics.nn.modules.conv.Concat           [1]                           
 15                  -1  1     37248  ultralytics.nn.modules.block.C2f             [192, 64, 1]                  
 16                  -1  1     36992  ultralytics.nn.modules.conv.Conv             [64, 64, 3, 2]                
 17            [-1, 12]  1         0  ultralytics.nn.modules.conv.Concat           [1]                           
 18                  -1  1    123648  ultralytics.nn.modules.block.C2f             [192, 128, 1]                 
 19                  -1  1    147712  ultralytics.nn.modules.conv.Conv             [128, 128, 3, 2]              
 20             [-1, 9]  1         0  ultralytics.nn.modules.conv.Concat           [1]                           
 21                  -1  1    493056  ultralytics.nn.modules.block.C2f             [384, 256, 1]                 
 22        [15, 18, 21]  1    751702  ultralytics.nn.modules.head.Detect           [2, 16, None, [64, 128, 256]] 
Model summary: 130 layers, 3,011,238 parameters, 3,011,222 gradients, 8.2 GFLOPs

Transferred 319/355 items from pretrained weights
Freezing layer 'model.22.dfl.conv.weight'
AMP: running Automatic Mixed Precision (AMP) checks...
AMP: checks passed 
train: Fast image access  (ping: 0.00.0 ms, read: 1838.31089.4 MB/s, size: 174.8 KB)
train: Scanning D:\PythonWorkspace\yolov8-tutorial\dataset\labels\train.cache... 98 images, 15 backgrounds, 0 corrupt: 100% ━━━━━━━━━━━━ 98/98  0.0s
val: Fast image access  (ping: 0.00.0 ms, read: 2107.01291.3 MB/s, size: 131.0 KB)
val: Scanning D:\PythonWorkspace\yolov8-tutorial\dataset\labels\val.cache... 24 images, 1 backgrounds, 0 corrupt: 100% ━━━━━━━━━━━━ 24/24  0.0s
optimizer: 'optimizer=auto' found, ignoring 'lr0=0.01' and 'momentum=0.937' and determining best 'optimizer', 'lr0' and 'momentum' automatically... 
optimizer: AdamW(lr=0.001667, momentum=0.9) with parameter groups 57 weight(decay=0.0), 64 weight(decay=0.0005), 63 bias(decay=0.0)
Plotting labels to D:\PythonWorkspace\yolov8-tutorial\runs\detect\my_model\labels.jpg... 
Image sizes 640 train, 640 val
Using 0 dataloader workers
Logging results to D:\PythonWorkspace\yolov8-tutorial\runs\detect\my_model
Starting training for 100 epochs...

      Epoch    GPU_mem   box_loss   cls_loss   dfl_loss  Instances       Size
      1/100      2.02G     0.6719      2.927      1.129          5        640: 100% ━━━━━━━━━━━━ 7/7 2.2it/s 3.3s
                 Class     Images  Instances      Box(P          R      mAP50  mAP50-95): 100% ━━━━━━━━━━━━ 1/1 2.2it/s 0.4s
                   all         24         30     0.0041          1      0.557      0.489

  ... 中間省略 ...

      Epoch    GPU_mem   box_loss   cls_loss   dfl_loss  Instances       Size
     90/100      2.18G      0.448     0.5201     0.9692          8        640: 100% ━━━━━━━━━━━━ 7/7 4.3it/s 1.6s
                 Class     Images  Instances      Box(P          R      mAP50  mAP50-95): 100% ━━━━━━━━━━━━ 1/1 3.1it/s 0.3s
                   all         24         30      0.936      0.938      0.979      0.758
Closing dataloader mosaic

  ... 中間省略 ...
  
      Epoch    GPU_mem   box_loss   cls_loss   dfl_loss  Instances       Size
    100/100      2.18G     0.3441     0.5115     0.8918          3        640: 100% ━━━━━━━━━━━━ 7/7 4.5it/s 1.6s
                 Class     Images  Instances      Box(P          R      mAP50  mAP50-95): 100% ━━━━━━━━━━━━ 1/1 3.1it/s 0.3s
                   all         24         30      0.851        0.9      0.941       0.69

100 epochs completed in 0.065 hours.
Optimizer stripped from D:\PythonWorkspace\yolov8-tutorial\runs\detect\my_model\weights\last.pt, 6.3MB
Optimizer stripped from D:\PythonWorkspace\yolov8-tutorial\runs\detect\my_model\weights\best.pt, 6.3MB

Validating D:\PythonWorkspace\yolov8-tutorial\runs\detect\my_model\weights\best.pt...
Ultralytics 8.4.37  Python-3.10.11 torch-2.11.0+cu130 CUDA:0 (NVIDIA GeForce RTX 2060 SUPER, 8192MiB)
Model summary (fused): 73 layers, 3,006,038 parameters, 0 gradients, 8.1 GFLOPs
                 Class     Images  Instances      Box(P          R      mAP50  mAP50-95): 100% ━━━━━━━━━━━━ 1/1 2.9it/s 0.3s
                   all         24         30       0.95      0.933      0.979       0.76
                   cat         18         25      0.899       0.92      0.964       0.57
                   dog          5          5          1      0.945      0.995       0.95
Speed: 0.2ms preprocess, 1.6ms inference, 0.0ms loss, 1.0ms postprocess per image
Results saved to D:\PythonWorkspace\yolov8-tutorial\runs\detect\my_model
訓練完成，總耗時：0 時 4 分 1 秒

Process finished with exit code 0

💡 訓練完成後，結果會自動儲存在 runs/detect/my_model/ 目錄下。

圖：YOLOv8 訓練 Log 重點解析 ─ 環境資訊、模型規格、訓練參數與過程總覽

圖：YOLOv8 train.cache 與 val.cache 說明 ─ 加速訓練與注意事項‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🧠 重要訓練參數說明

圖：YOLOv8 train 完整參數表 ─ 16 個常用參數與預設值說明

💡 模型選擇建議

圖：YOLOv8 三種起點模型選擇 ─ 從預訓練權重微調、從頭訓練到繼續中斷的 checkpoint

① 從預訓練權重微調（一般情況，推薦）
載入 Ultralytics 在 COCO 資料集上訓練好的權重，再用自己的資料繼續訓練。模型已具備基本的影像辨識能力，收斂快、所需資料量少，是最常見的做法。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

1
2
3

# demo_pretrained.py
from ultralytics import YOLO
model = YOLO("yolov8n.pt")  # 第一次執行會自動下載，約 6MB

② 從頭訓練（特殊情況）
只載入網路架構定義，權重全部隨機初始化，需要大量資料（通常數千張以上）才能訓練出好的模型。若你的類別與 COCO 差異極大（例如醫療影像、衛星圖）才考慮。

1
2
3

# demo_from_scratch.py
from ultralytics import YOLO
model = YOLO("yolov8n.yaml")  # 只有架構，無預訓練權重

③ 繼續訓練中斷的 checkpoint
訓練途中若因斷電、關機等原因中斷，可從上次儲存的 last.pt 繼續，不需要從頭跑。詳細用法見本篇 [中斷後繼續訓練] 章節。

1
2
3

# demo_resume.py
from ultralytics import YOLO
model = YOLO("runs/detect/my_model/weights/last.pt")

💻 多張 GPU 訓練

device 參數的常用值：0（第一張 GPU）、"0,1"（雙 GPU）、"cpu"（強制使用 CPU）。
有多張 GPU 時，可用以下方式自動偵測並全部啟用：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# setup_gpu.py
import torch
from ultralytics import YOLO

gpu_count = torch.cuda.device_count()
device = ",".join(str(i) for i in range(gpu_count)) if gpu_count >= 2 else 0
print(f"偵測到 {gpu_count} 張 GPU，使用 device={device!r}")

model = YOLO("yolov8n.pt")
model.train(data="data.yaml", epochs=100, device=device)

⛃ GPU 記憶體不足（OOM）

圖：GPU 記憶體使用原理 ─ batch 和 imgsz 是最吃記憶體的兩個參數

訓練時 GPU 需要把圖片、模型權重、梯度全部同時放進記憶體計算。
batch（每次丟幾張圖）和 imgsz（每張圖的解析度）是最吃記憶體的兩個設定：

batch=16 表示每次同時處理 16 張圖，16 張的資料都要同時放進 GPU
imgsz=640 表示每張圖縮放到 640×640，解析度越高，每張圖佔的記憶體越大

兩個值相乘就是每次計算的「記憶體負擔」。以 8GB 顯卡為例：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

batch=16, imgsz=640 → 可能剛好 OOM
batch=8, imgsz=640 → 記憶體砍半，通常能跑
batch=8, imgsz=416 → 更小，適合記憶體非常有限的環境

訓練啟動後若出現以下錯誤，就是記憶體不夠：

1	RuntimeError: CUDA out of memory.

依序嘗試以下調整，直到不再 OOM：

# fix_oom.py
import torch
from ultralytics import YOLO

model = YOLO("yolov8n.pt")

# 方法一：先縮小 batch（優先嘗試，對準確度影響較小）
model.train(data="data.yaml", epochs=100, imgsz=640, batch=8,
            device=0 if torch.cuda.is_available() else "cpu")

# 方法二：batch 和 imgsz 同時縮小（記憶體非常有限時）
# model.train(data="data.yaml", epochs=100, imgsz=416, batch=8,
#             device=0 if torch.cuda.is_available() else "cpu")

💻 中斷後繼續訓練

YOLOv8 每個 epoch 都會儲存 last.pt，可隨時從中斷點繼續：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# resume_training.py
from ultralytics import YOLO

# 方法一：Python API
model = YOLO("runs/detect/my_model/weights/last.pt")
model.train(resume=True)

# 方法二：指令列
# yolo detect train resume model=runs/detect/my_model/weights/last.pt

⚠️ 注意事項

CPU 訓練速度非常慢：無 GPU 環境下，100 epochs 可能需要數小時甚至更長。第一次執行建議先將 epochs 設為 3~5，確認資料集路徑、格式、流程都正確後，再調回正式輪數。若需要完整訓練，強烈建議使用有 CUDA 的環境或 Google Colab（免費 GPU）。
Windows 上 workers 需設為 0：設成其他數值可能造成 DataLoader 死鎖，訓練無法啟動。
batch=-1 自動計算：可設定 batch=-1 讓 YOLOv8 根據 GPU 記憶體自動計算最大 batch size，但不夠穩定，建議手動設定。
訓練過程中不要刪除 runs/ 目錄：中斷恢復需要依賴其中的 last.pt 與 args.yaml。

🎯 結語

YOLOv8 的基本訓練流程相當精簡，幾行程式碼就能啟動，並內建快取、自動儲存與斷點恢復等機制。
下一步是 YOLOv8 訓練進階設定，介紹資料增強與防止過擬合的進階參數調整。

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
Ultralytics YOLOv8 官方文件 — Train
Ultralytics YOLOv8 官方文件 — Configuration‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Python | OpenCV YOLOv8 預標籤（Pre-Label）

2026-04-08T01:00:00.000Z

📚 前言

在上一篇 YOLOv8 資料集準備 中，我們完成了圖片蒐集、標註與資料集切分。
手動標記雖然精確，但對大量圖片來說非常耗時。

如果你要標記的類別（例如 cat、dog）剛好在 YOLOv8 預訓練模型支援的 COCO 80 類別內，可以先讓模型跑一遍推論，自動產生標籤草稿，再用 LabelImg 只修正錯誤的框，速度可以快上數倍。

🔎 預標籤的原理與流程

YOLOv8 的 COCO 預訓練模型已經學會辨識 80 種常見物件（包含 cat、dog）。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🔸 如何確認 yolov8n.pt 是用 COCO 訓練的？只有 80 類？

你可以執行以下程式碼來驗證：

# check_coco_classes.py
from ultralytics import YOLO

model = YOLO("yolov8n.pt")
print("類別總數：", len(model.names))
print("類別對照表：", model.names)

執行後你會看到：

類別總數為 80
類別名稱包含 person、car、cat、dog 等常見物件

類別總數： 80
類別對照表： {
0: 'person', 1: 'bicycle', 2: 'car', 3: 'motorcycle', 4: 'airplane', 5: 'bus', 
6: 'train', 7: 'truck', 8: 'boat', 9: 'traffic light', 10: 'fire hydrant', 
11: 'stop sign', 12: 'parking meter', 13: 'bench', 14: 'bird', 15: 'cat', 
16: 'dog', 17: 'horse', 18: 'sheep', 19: 'cow', 20: 'elephant', 
21: 'bear', 22: 'zebra', 23: 'giraffe', 24: 'backpack', 25: 'umbrella', 
26: 'handbag', 27: 'tie', 28: 'suitcase', 29: 'frisbee', 30: 'skis', 
31: 'snowboard', 32: 'sports ball', 33: 'kite', 34: 'baseball bat', 35: 'baseball glove', 
36: 'skateboard', 37: 'surfboard', 38: 'tennis racket', 39: 'bottle', 40: 'wine glass', 
41: 'cup', 42: 'fork', 43: 'knife', 44: 'spoon', 45: 'bowl', 
46: 'banana', 47: 'apple', 48: 'sandwich', 49: 'orange', 50: 'broccoli', 
51: 'carrot', 52: 'hot dog', 53: 'pizza', 54: 'donut', 55: 'cake', 
56: 'chair', 57: 'couch', 58: 'potted plant', 59: 'bed', 60: 'dining table', 
61: 'toilet', 62: 'tv', 63: 'laptop', 64: 'mouse', 65: 'remote', 
66: 'keyboard', 67: 'cell phone', 68: 'microwave', 69: 'oven', 70: 'toaster', 
71: 'sink', 72: 'refrigerator', 73: 'book', 74: 'clock', 75: 'vase', 
76: 'scissors', 77: 'teddy bear', 78: 'hair drier', 79: 'toothbrush'
}

這就是官方 COCO 資料集的 80 個類別。因此只有這些類別才能使用預標籤功能。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🔸 原理說明

YOLOv8 的 COCO 預訓練模型能偵測 80 種物件，偵測結果包含：

類別 ID（對應 COCO 80 類）
邊界框座標（已是相對比例，可直接寫入 YOLO txt）

圖：pre_label.py 自動預標籤流程 ─ 用 YOLOv8 預訓練模型快速產生初始標註的 6 個步驟

💡 COCO 資料集中 cat 的 class_id 是 15，dog 是 16，與我們 data.yaml 定義的 0、1 不同，必須重新對應，否則 class_id 會錯。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🧠 函式與參數說明

圖：YOLOv8 偵測結果重要屬性 ─ box.xywhn（正規化座標）與 conf（信心度門檻）說明

💻 範例程式

# pre_label.py
import os
from ultralytics import YOLO

# ── 設定 ────────────────────────────────────
model_path     = "yolov8n.pt"   # 預訓練模型，第一次執行會自動下載
src_dir        = "raw_images"   # 原始圖片目錄（與 20260407 的 download_images.py 輸出一致）
dst_dir        = "raw_labels"   # 標籤輸出目錄
conf_threshold = 0.5            # 信心度門檻，低於此值的偵測結果會被過濾
target_classes = {"cat": 0, "dog": 1}  # 只保留這些類別，並重新對應為 0-based class_id
# ────────────────────────────────────────────

model      = YOLO(model_path)
coco_names = model.names  # COCO 80 類別名稱對照表（dict: id → name）

os.makedirs(dst_dir, exist_ok=True)

# 產生 classes.txt，LabelImg 需要此檔案才能正確對應類別名稱
classes_txt = os.path.join(dst_dir, "classes.txt")
with open(classes_txt, "w") as f:
    for name in sorted(target_classes, key=target_classes.get):
        f.write(name + "\n")

img_files = [f for f in os.listdir(src_dir)
             if f.lower().endswith((".jpg", ".jpeg", ".png"))]

for fname in img_files:
    img_path = os.path.join(src_dir, fname)
    stem     = os.path.splitext(fname)[0]
    lbl_path = os.path.join(dst_dir, stem + ".txt")

    results = model(img_path, conf=conf_threshold, verbose=False)[0]
    lines   = []

    for box in results.boxes:
        coco_cls_id = int(box.cls)
        coco_name   = coco_names[coco_cls_id]
        if coco_name not in target_classes:
            continue  # 過濾不需要的類別

        new_cls_id     = target_classes[coco_name]
        x, y, w, h     = box.xywhn[0].tolist()  # 已是相對比例，直接使用
        lines.append(f"{new_cls_id} {x:.6f} {y:.6f} {w:.6f} {h:.6f}")

    with open(lbl_path, "w") as f:
        f.write("\n".join(lines))

    status = f"{len(lines)} 個標籤" if lines else "無偵測結果（空標籤）"
    print(f"{fname}: {status}")

print(f"\n完成：共處理 {len(img_files)} 張圖片，標籤輸出至 {dst_dir}/")

圖：對 raw_images/ 批次推論並輸出 YOLO txt 標籤至 raw_labels/，顯示每張圖片的偵測數量

💻 用 LabelImg 修正標籤

執行完 pre_label.py 後，raw_labels/ 已有自動產生的標籤草稿。接著用 LabelImg 開啟修正：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

Open Dir：選擇 raw_images/
Change Save Dir：選擇 raw_labels/（LabelImg 會自動載入同名的 .txt）
儲存格式切換為 YOLO
逐張檢查，刪除錯誤的框、補畫漏標的物件、修正類別
Ctrl + S 儲存後按 D 切到下一張

圖：在 LabelImg 中載入自動產生的標籤草稿，修正偵測錯誤的邊界框

💡 pre_label.py 執行時會自動產生 raw_labels/classes.txt，LabelImg 需要此檔案才能正確對應類別名稱，不需要手動建立。

🔄 後續步驟：完成資料集準備

預標籤只是取代了 YOLOv8 資料集準備 中的「步驟 2：手動標註」，完整的資料集流程到這裡還剩三個步驟尚未完成：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

步驟	腳本	說明
步驟 3	`split_dataset.py`	將 `raw_images/` 與 `raw_labels/` 隨機分割為訓練集（80%）與驗證集（20%）
步驟 4	`create_yaml.py`	產生 `data.yaml`，告訴 YOLOv8 資料集路徑與類別定義
步驟 5	`verify_dataset.py`	驗證所有圖片與標籤的格式、對應關係、class_id 範圍

這三個腳本的完整程式碼與說明請參考 YOLOv8 資料集準備 的步驟 3～5。

⚠️ 省略驗證步驟直接訓練，是訓練時「資料集格式錯誤」或「一直用舊資料」的最常見原因。

⚠️ 注意事項

只適用於 COCO 80 類別內的物件：若你要標記的類別不在 COCO 80 類別內（例如特定商品、自訂符號），預標籤無法使用，只能全手動或先用少量資料訓練一個初版模型再回頭預標。
預標籤不等於正確標籤：模型可能漏標、誤標，每張圖都必須人工確認，不能直接用於訓練。
空標籤檔案需保留：模型未偵測到目標的圖片，pre_label.py 會輸出空的 .txt，這是正確的 YOLO 格式，不要刪除。
信心度門檻影響標籤品質：conf 設太低會產生大量誤標框，設太高會漏掉部分真實物件，建議先用 0.5 再依實際結果調整。

📊 應用場景

大量圖片需要標記：100 張以上的資料集，預標籤可以省去大部分畫框時間，只需修正。
新類別自訓練的冷啟動：先用 COCO 預標籤標出相近類別（例如用 person 預標人物），修正後訓練初版模型，再用初版模型回頭預標更多資料，形成正向循環。

🎯 結語

預標籤不是讓你省掉標記，而是把「從零畫框」變成「改錯」，後者快得多。
完成標籤修正後，別忘了回到 YOLOv8 資料集準備 完成剩餘三個步驟：用 split_dataset.py 切分資料集、用 create_yaml.py 產生 data.yaml、再用 verify_dataset.py 驗證格式無誤，才算真正備妥訓練資料。
下一步是 YOLOv8 模型訓練，正式把資料送入模型開始學習。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
Ultralytics YOLOv8 官方文件 — Predict
Ultralytics YOLOv8 官方文件 — Results
COCO Dataset — Categories

Python | OpenCV YOLOv8 資料集準備

2026-04-07T01:00:00.000Z

📚 前言

在上一篇 YOLOv8 介紹與環境安裝 中，我們完成了環境設定並測試了預訓練模型。
這一篇進入自訓練的第一步：準備自己的資料集。

YOLOv8 對資料集的格式要求非常嚴格，如果格式錯誤，訓練時就會直接報錯。因此我們必須一步一步按照正確流程來做。

完整流程如下：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

走完這些步驟後，你的專案目錄會變成這樣：

project/
├── raw_images/          ← 蒐集的原始圖片
├── raw_labels/          ← LabelImg 標註輸出
├── dataset/             ← split_dataset.py 切分後的訓練資料
│   ├── images/
│   │   ├── train/
│   │   └── val/
│   └── labels/
│       ├── train/
│       └── val/
├── data.yaml            ← create_yaml.py 產生
├── download_images.py
├── split_dataset.py
├── create_yaml.py
└── verify_dataset.py

🗃️ 步驟 1：蒐集圖片

與分類任務不同，物件偵測的原始圖片不需要分類別放進不同資料夾，全部放在同一個資料夾即可。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

以下是使用 Bing 搜尋引擎批量下載圖片的範例：

# download_images.py
from icrawler.builtin import BingImageCrawler

keywords = ["cat", "dog"]   # 你想要偵測的類別

for kw in keywords:
    crawler = BingImageCrawler(storage={"root_dir": "raw_images"})
    crawler.crawl(keyword=kw, max_num=200)   # 建議每類至少 100~200 張

圖：使用 BingImageCrawler 批次下載 cat 與 dog 圖片至 raw_images 目錄

⚠️ 注意版權問題，建議僅用於研究與學習目的。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

💻 步驟 2：使用 LabelImg 進行標註

LabelImg 的完整安裝、操作步驟與已知的 PyQt5 崩潰修法，已在 LabelImg 標註工具實戰 篇完整說明，這裡只補充 YOLOv8 工作流程中特有的設定：

標註時需要注意以下重點：

Open Dir：選擇 raw_images/ 資料夾
Change Save Dir：選擇 raw_labels/ 資料夾（建議先分開存放）
儲存格式：務必切換成 YOLO 格式（不是 Pascal VOC）
每張圖片標註完後，會產生一個同名的 .txt 檔案

圖：在 LabelImg 中設定 Open Dir 為 raw_images/、Change Save Dir 為 raw_labels/，並切換儲存格式為 YOLO‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

💡 若想減少手動標記的工作量，可先參考 YOLOv8 預標籤 篇，讓模型自動產生標籤草稿，再用 LabelImg 修正。

✂️ 步驟 3：自動分割訓練集與驗證集

標註完成後，使用以下腳本自動切分資料（推薦 80% 訓練集、20% 驗證集）：
YOLOv8 要求的結構，需要的是 images/ 和 labels/ 分開的結構，以下是對應的版本：

dataset/
├── images/
│   ├── train/          ← 訓練集圖片
│   │   ├── 0001.jpg
│   │   └── ...
│   └── val/            ← 驗證集圖片
│       ├── 0101.jpg
│       └── ...
└── labels/
    ├── train/          ← 訓練集標籤（與 images/train/ 一一對應）
    │   ├── 0001.txt
    │   └── ...
    └── val/            ← 驗證集標籤（與 images/val/ 一一對應）
        ├── 0101.txt
        └── ...

重要規則：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

images/ 與 labels/ 的子目錄結構必須完全對應
圖片檔名與標籤檔名必須相同（只有副檔名不同）
例如 images/train/0001.jpg → labels/train/0001.txt
訓練集與驗證集的比例建議為 80% / 20%

# split_dataset.py
import os
import shutil
import random

src_images = "raw_images"       # 原始圖片目錄
src_labels = "raw_labels"       # 原始標籤目錄
dst_root   = "dataset"          # 輸出目錄
val_ratio  = 0.2                # 驗證集比例
random.seed(42)

for split in ["train", "val"]:
    os.makedirs(f"{dst_root}/images/{split}", exist_ok=True)
    os.makedirs(f"{dst_root}/labels/{split}", exist_ok=True)

files = [f for f in os.listdir(src_images)
         if f.lower().endswith((".jpg", ".jpeg", ".png"))]
random.shuffle(files)

val_count = int(len(files) * val_ratio)
val_files = set(files[:val_count])

for fname in files:
    split    = "val" if fname in val_files else "train"
    stem     = os.path.splitext(fname)[0]
    label_fn = stem + ".txt"

    shutil.copy(
        os.path.join(src_images, fname),
        os.path.join(dst_root, "images", split, fname)
    )
    label_src = os.path.join(src_labels, label_fn)
    if os.path.exists(label_src):
        shutil.copy(label_src,
                    os.path.join(dst_root, "labels", split, label_fn))
    else:
        # 無標註物件的圖片，建立空標籤檔
        open(os.path.join(dst_root, "labels", split, label_fn), "w").close()

print(f"完成：train={len(files)-val_count} 張，val={val_count} 張")

圖：自動依比例將圖片與標籤隨機分割為訓練集與驗證集，並建立對應的目錄結構

🧠 步驟 4：產生 data.yaml 設定檔

data.yaml 是告訴 YOLOv8 資料集位置與類別定義的設定檔，訓練時必須指定。跑完 split_dataset.py 後建立，放在專案根目錄（與 dataset/ 同層）：

project/
├── raw_images/
├── raw_labels/
├── dataset/
│   ├── images/
│   │   ├── train/
│   │   └── val/
│   └── labels/
│       ├── train/
│       └── val/
├── data.yaml            ← 放這裡
├── create_yaml.py
└── split_dataset.py

# create_yaml.py
import yaml

data = {
    "path": "./dataset",           # 資料集根目錄
    "train": "images/train",       # 訓練集圖片相對路徑
    "val": "images/val",           # 驗證集圖片相對路徑
    "nc": 2,                       # 類別數量（cat 和 dog → 2）
    "names": {0: "cat", 1: "dog"}  # class_id 對應的類別名稱
}

with open("data.yaml", "w", encoding="utf-8") as f:
    yaml.dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False)

print("data.yaml 已成功產生！")

產生的 data.yaml 內容範例：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

path: ./dataset
train: images/train
val: images/val
nc: 2
names:
  0: cat
  1: dog

⚠️ names 的順序就是標註時的 class_id，必須與標籤檔案中的 ID 完全對應，不能錯位。

圖：執行 create_yaml.py 自動產生 data.yaml 設定檔

💻 步驟 5：驗證資料集格式

在開始訓練前，務必執行驗證，避免格式錯誤導致訓練失敗：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

# verify_dataset.py
import os
import cv2

def verify_dataset(img_dir, lbl_dir, class_names):
    errors = []
    for fname in os.listdir(img_dir):
        if not fname.lower().endswith((".jpg", ".jpeg", ".png")):
            continue
        stem     = os.path.splitext(fname)[0]
        img_path = os.path.join(img_dir, fname)
        lbl_path = os.path.join(lbl_dir, stem + ".txt")

        img = cv2.imread(img_path)
        if img is None:
            errors.append(f"圖片損壞：{img_path}")
            continue

        if not os.path.exists(lbl_path):
            errors.append(f"缺少標籤：{lbl_path}")
            continue

        h, w = img.shape[:2]
        with open(lbl_path) as f:
            for i, line in enumerate(f):
                parts = line.strip().split()
                if not parts:
                    continue  # 跳過空行（檔案結尾的換行符）
                if len(parts) != 5:
                    errors.append(f"格式錯誤（{lbl_path} 第{i+1}行）")
                    continue
                cls_id = int(parts[0])
                if cls_id >= len(class_names):
                    errors.append(f"class_id 超出範圍（{lbl_path} 第{i+1}行）")

    if errors:
        print(f"發現 {len(errors)} 個問題：")
        for e in errors:
            print(f"  ✗ {e}")
    else:
        print("✅ 資料集格式驗證通過")

verify_dataset("dataset/images/train", "dataset/labels/train",
               class_names=["cat", "dog"])  # 依實際類別修改，順序須與 data.yaml 的 names 一致

圖：逐一檢查圖片與標籤的對應關係、格式正確性及 class_id 範圍，輸出驗證結果

✨ 補充說明

YOLO txt 格式在 LabelImg 實際產出的座標是怎麼計算的，方便理解標籤檔的內容。

每張圖片對應一個同名 .txt，每行一個物件：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

所有座標都是相對比例（0.0 ~ 1.0），不是像素值。以一張 640×480 的圖片為例，貓（class_id=0）的邊界框左上角在 (100, 80)、右下角在 (300, 280)：

x_center = (100 + 300) / 2 / 640 = 0.3125
y_center = (80  + 280) / 2 / 480 = 0.375
width    = (300 - 100) / 640     = 0.3125
height   = (280 -  80) / 480     = 0.4167

# 寫入 .txt 的內容
0 0.3125 0.375 0.3125 0.4167

若同一張圖片有多個物件，每行寫一個：

1 2	0 0.3125 0.375 0.3125 0.4167 1 0.7500 0.600 0.2000 0.3000

💡 若圖片中沒有任何標註物件，對應的 .txt 應為空檔案，而非不存在。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

⚠️ 注意事項

類別 ID 從 0 開始：標籤檔案中的 class_id 必須從 0 開始，且不能有跳號。
圖片與標籤一定要一一對應：若有圖片沒有對應的 .txt，YOLOv8 訓練時會報錯。
座標必須是相對比例：絕對像素座標不是有效的 YOLO 格式，必須換算成 0.0~1.0 的比例值。
建議圖片解析度一致：不同解析度的圖片混在一起沒有問題，YOLOv8 會自動 resize，但解析度差異太大可能影響訓練效果。

🎯 結語

資料集準備是 YOLOv8 自訓練最重要也最容易出錯的步驟。

只要確實按照「蒐集 → 標註 → 分割 → 產生 yaml → 驗證」的順序來做，並在最後一步用 verify_dataset.py 確認無誤，就可以放心進入訓練階段。

下一步是 YOLOv8 預標籤（Pre-Label），學習如何利用預訓練模型自動產生標籤草稿，減少手動標記的工作量。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
Ultralytics YOLOv8 官方文件 — Datasets
LabelImg GitHub

Python | OpenCV YOLOv8 介紹與環境安裝

2026-04-06T10:00:00.000Z

📚 前言

在 從分類到偵測 — YOLOv8 系列介紹 中說明了分類與偵測任務的差異，以及這個子系列的學習路線。
如果你的目標是「在圖片中找出物件的位置」，也就是物件偵測任務，就需要不同的模型與訓練方式。

YOLOv8 是目前最主流的即時物件偵測框架，由 Ultralytics 開發與維護。
這個系列文章將帶你從環境安裝開始，一路到用自己的資料集訓練出專屬的偵測模型。

🔎 什麼是 YOLO？

YOLO（You Only Look Once）是一系列即時物件偵測模型的統稱。
與傳統的兩階段偵測器（如 Faster R-CNN）不同，YOLO 只需一次前向傳播就能同時預測所有物件的位置與類別，速度極快。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

YOLOv8 是第八代，由 Ultralytics 在 2023 年發布，相較前代有以下特點：

更高的偵測準確度（mAP）
更快的推論速度
統一的 Python API，支援偵測、分割、分類、姿態估計等多種任務
內建訓練、驗證、推論、匯出等完整工具鏈

🧠 模型規格與選擇

圖：YOLOv8 五種模型規格比較 ─ 從 nano 到 extra 的參數量、準確度、速度與推薦情境

💡 建議先用 yolov8n 或 yolov8s 跑通訓練流程，確認資料沒問題後，再換較大的模型提升準確度。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🛠️ 環境安裝

本系列後續所有範例皆以 GPU 執行為主。

相關環境安裝文章：

1 2	# 安裝 ultralytics pip install ultralytics

💻 驗證安裝

# verify_install.py
import torch
import ultralytics

# 確認 GPU 可用
print(torch.cuda.is_available())       # True
print(torch.cuda.get_device_name(0))   # 顯卡名稱

# 確認 ultralytics 環境
ultralytics.checks()

正常輸出範例（GPU）：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

True
NVIDIA GeForce RTX XXXX
Ultralytics YOLOv8.x.x 🚀 Python-3.10.x torch-2.x.x CUDA:0 (NVIDIA GeForce RTX XXXX, XXXXMB)
Setup complete ✅ (8 CPUs, 16.0 GB RAM, 100.0 GB disk)

💡 若 torch.cuda.is_available() 回傳 False，代表 PyTorch 的 GPU 版本未正確安裝，請重新確認 CUDA 版本並參照 pytorch.org 安裝對應版本。

💻 使用預訓練模型快速測試

安裝完成後，我們可以用 Ultralytics 提供的 CLI（指令列）方式快速測試 YOLOv8 是否正常運作。
YOLOv8 的 CLI 非常方便，適合快速驗證環境與模型效果。

💡 以下範例使用的 yolov8n.pt 是以 COCO 資料集預訓練的權重，能偵測 80 種常見物件（人、車、動物、家電、食物、家具等）。若目標物件不在這 80 類內，則需要自行蒐集資料訓練自訂模型，這正是後續幾篇要介紹的重點。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🔹 使用指令列（CLI）快速測試

🔸 偵測單張圖片

⌨ 指令：

1 2	# 偵測圖片（使用 Ultralytics 官方測試圖片，第一次執行會自動下載模型權重） yolo detect predict model=yolov8n.pt source="https://ultralytics.com/images/bus.jpg"

🖥️ 輸出：

Ultralytics 8.4.26  Python-3.10.11 torch-2.11.0+cu130 CUDA:0 (NVIDIA GeForce RTX 2060 SUPER, 8192MiB)
YOLOv8n summary (fused): 72 layers, 3,151,904 parameters, 0 gradients, 8.7 GFLOPs

Found https://ultralytics.com/images/bus.jpg locally at bus.jpg
image 1/1 D:\PythonWorkspace\opencv-tutorial\bus.jpg: 640x480 4 persons, 1 bus, 1 stop sign, 27.1ms
Speed: 1.9ms preprocess, 27.1ms inference, 12.6ms postprocess per image at shape (1, 3, 640, 480)
Results saved to D:\PythonWorkspace\opencv-tutorial\runs\detect\predict
 Learn more at https://docs.ultralytics.com/modes/predict

📝 說明：這是測試環境是否正常的最簡單方式。模型會自動偵測圖片中的物件，並在終端機顯示偵測到的類別與信心度，同時會把結果圖片儲存到 runs/detect/predict 資料夾。

🔸 偵測本地圖片

⌨ 指令：

1 2	# 偵測本地圖片（street.jpg 為「OpenCV 與深度學習框架整合」篇使用的 Pexels 街景素材） yolo detect predict model=yolov8n.pt source=assets/street.jpg

🖥️ 輸出：

Ultralytics 8.4.26  Python-3.10.11 torch-2.11.0+cu130 CUDA:0 (NVIDIA GeForce RTX 2060 SUPER, 8192MiB)
YOLOv8n summary (fused): 72 layers, 3,151,904 parameters, 0 gradients, 8.7 GFLOPs

image 1/1 D:\PythonWorkspace\opencv-tutorial\assets\street.jpg: 448x640 1 person, 7 cars, 2 buss, 28.7ms
Speed: 2.2ms preprocess, 28.7ms inference, 12.0ms postprocess per image at shape (1, 3, 448, 640)
Results saved to D:\PythonWorkspace\opencv-tutorial\runs\detect\predict
 Learn more at https://docs.ultralytics.com/modes/predict

📝 說明：把 source 改成你本機的圖片路徑即可。結果圖片會自動儲存，並在終端機顯示偵測到的物件數量與類別。

🔸 偵測影片

⌨ 指令：

1 2	# 偵測影片（street.mp4 同上） yolo detect predict model=yolov8n.pt source=assets/street.mp4

🖥️ 輸出：

Ultralytics 8.4.26  Python-3.10.11 torch-2.11.0+cu130 CUDA:0 (NVIDIA GeForce RTX 2060 SUPER, 8192MiB)
YOLOv8n summary (fused): 72 layers, 3,151,904 parameters, 0 gradients, 8.7 GFLOPs

video 1/1 (frame 1/93) D:\PythonWorkspace\opencv-tutorial\assets\street.mp4: 384x640 8 persons, 2 cars, 3 traffic lights, 1 handbag, 20.4ms
video 1/1 (frame 2/93) D:\PythonWorkspace\opencv-tutorial\assets\street.mp4: 384x640 8 persons, 2 cars, 3 traffic lights, 1 handbag, 7.6ms
... 省略 ...
video 1/1 (frame 91/93) D:\PythonWorkspace\opencv-tutorial\assets\street.mp4: 384x640 15 persons, 1 car, 3 traffic lights, 7.6ms
video 1/1 (frame 92/93) D:\PythonWorkspace\opencv-tutorial\assets\street.mp4: 384x640 12 persons, 1 car, 2 traffic lights, 7.4ms
video 1/1 (frame 93/93) D:\PythonWorkspace\opencv-tutorial\assets\street.mp4: 384x640 12 persons, 1 car, 2 traffic lights, 7.4ms
Speed: 1.3ms preprocess, 7.8ms inference, 1.6ms postprocess per image at shape (1, 3, 384, 640)
Results saved to D:\PythonWorkspace\opencv-tutorial\runs\detect\predict
 Learn more at https://docs.ultralytics.com/modes/predict

📝 說明：YOLOv8 會逐幀處理影片，並在終端機顯示每幀的偵測結果。處理完後會自動把帶有偵測框的影片儲存起來。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🔸 即時攝影機偵測

⌨ 指令：

1 2	# 即時攝影機偵測（需有攝影機，0 代表預設裝置） yolo detect predict model=yolov8n.pt source=0

🖥️ 輸出：

Ultralytics 8.4.26  Python-3.10.11 torch-2.11.0+cu130 CUDA:0 (NVIDIA GeForce RTX 2060 SUPER, 8192MiB)
YOLOv8n summary (fused): 72 layers, 3,151,904 parameters, 0 gradients, 8.7 GFLOPs

[ WARN:0@0.001] global cap_ffmpeg_impl.hpp:1217 open VIDEOIO/FFMPEG: Failed list devices for backend dshow
[ERROR:0@2.857] global obsensor_uvc_stream_channel.cpp:163 cv::obsensor::getStreamChannelGroup Camera index out of range
... 省略 ...
ConnectionError: 1/1: 0... Failed to open 0

📝 說明：如果出現類似錯誤，通常是因為沒有連接攝影機，或攝影機被其他程式占用。解決方式：確認攝影機已連接，並關閉其他可能使用攝影機的程式（例如 Zoom、Teams、Camera App）。成功時會開啟一個視窗，即時顯示偵測結果。

🔹 Python API 方式

# inference.py
from ultralytics import YOLO

# 載入預訓練模型（自動下載 yolov8n.pt）
model = YOLO("yolov8n.pt")

# 對圖片推論（使用 Ultralytics 官方測試圖片）
results = model("https://ultralytics.com/images/bus.jpg")

# 顯示結果
results[0].show()

# 查看偵測到的物件
for box in results[0].boxes:
    cls_id = int(box.cls)
    conf   = float(box.conf)
    label  = model.names[cls_id]
    print(f"偵測到：{label}，信心度：{conf:.2f}")

圖：使用 YOLOv8 Python API 載入預訓練模型對圖片推論並輸出偵測到的物件類別與信心度

⚠️ 注意事項

第一次執行會自動下載模型權重：yolov8n.pt 約 6MB，yolov8x.pt 約 130MB，需要網路連線。
ultralytics 會將下載的模型快取在 ~/.cache/ultralytics/（或 Windows 的 %USERPROFILE%\.cache\ultralytics\）。
PyTorch 版本需與 CUDA 版本對應：安裝時請至 pytorch.org 確認當前 CUDA 版本對應的 --index-url，版本不符會導致安裝到 CPU 版本。

📊 應用場景

快速驗證可行性：用預訓練模型先測試偵測效果，確認方向後再進入自訓練流程。
直接部署通用偵測：若目標物件恰好在 COCO 80 類別內，可直接使用預訓練模型而無需訓練。

🎯 結語

YOLOv8 的環境設定相當簡單，pip install ultralytics 就能擁有完整的工具鏈。
下一步是 YOLOv8 資料集準備，學習如何組織自己的資料，讓 YOLOv8 能夠讀取並訓練。‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

📖 如在學習過程中遇到疑問，或是想了解更多相關主題，建議回顧一下 Python | OpenCV 系列導讀，掌握完整的章節目錄，方便快速找到你需要的內容。

註：以上參考了
Ultralytics YOLOv8 官方文件
 Ultralytics GitHub

Python | OpenCV 從分類到偵測 — YOLOv8 系列介紹

2026-04-06T01:00:00.000Z

📚 前言

在上一篇 與 OpenCV 整合推論 結束後，我們完整走過了一個圖片分類模型從訓練到部署的全流程：

這些章節以「圖片分類」為核心，從原理一路走到實際部署。
但如果你的目標是「在圖片中框出物件的位置並標出類別」，也就是物件偵測，那就是另一回事了。

🔎 圖片分類 vs 物件偵測

圖：圖片分類 vs 物件偵測 ─ 兩者核心差異比較（輸出、問題、標註成本、模型複雜度）‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

前面章節用 ResNet 做分類，可以判斷「這張圖是貓還是狗」。
但如果想知道「這張圖裡有幾隻貓、分別在哪個位置」，ResNet 就不夠用了，需要物件偵測模型。

💡 為什麼 YOLOv8 值得獨立一個系列

YOLO（You Only Look Once）是目前最主流的即時物件偵測框架，而 YOLOv8 是由 Ultralytics 維護的第八代版本。

把它拉出來獨立成系列，原因有幾個：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

訓練方式截然不同
前面章節的分類訓練需要手刻資料集 class、模型結構、訓練迴圈。
YOLOv8 只需準備一個 YAML 設定檔描述資料集路徑與類別，一行指令就能開始訓練：

1	yolo detect train data=my_dataset.yaml model=yolov8n.pt epochs=50

這種極度簡化的 API 背後，是 Ultralytics 整合好的訓練、驗證、早停、日誌、模型儲存等全套機制。

圖：YOLOv8 的兩大核心優勢 ─ 任務支援範圍廣 + 推論與匯出極度方便‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

前面學的知識仍然有用
前幾章說明的 PyTorch 基礎、遷移學習原理、資料增強、模型評估方式，在 YOLO 的底層都是一樣的概念。
YOLO 系列是站在那些基礎上，學習如何用更高層的工具更快完成物件偵測任務。

📋 YOLO 系列文章架構

圖：YOLOv8 系列文章架構 ─ 建議按順序閱讀的完整學習路徑

接下來的系列會依這個順序展開，建議按順序閱讀：‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌

🔹 YOLOv8 介紹與環境安裝

你將學到：YOLOv8 的五種模型規格（n/s/m/l/x）怎麼選、安裝 Ultralytics、驗證環境、用預訓練模型跑第一次推論。
這是整個 YOLO 系列的起點，跑通這篇才能接著做資料準備與訓練。
📖 詳細說明請參考：YOLOv8 介紹與環境安裝

🔹 YOLOv8 資料集準備

你將學到：YOLO 格式的標註檔結構（.txt）、資料集目錄配置、撰寫 dataset.yaml、切分 train/val/test。
YOLO 的資料格式與前面章節的分類格式完全不同，這篇說明如何正確組織。
📖 詳細說明請參考：YOLOv8 資料集準備

🔹 YOLOv8 預標籤（Pre-Label）

你將學到：用 COCO 預訓練模型對圖片自動框出初始標註，再用標註工具做人工修正，大幅降低標註工時。
完全手動標一張圖需要數十秒，預標籤可以讓這個成本降到只需「確認與微調」。
📖 詳細說明請參考：YOLOv8 預標籤（Pre-Label）

🔹 YOLOv8 模型訓練

你將學到：yolo train 指令與常用參數（epochs、imgsz、batch）、斷點續訓、用 Python API 訓練、訓練過程中的輸出目錄結構。
一行指令就能啟動訓練，但參數設定對結果影響很大，這篇說明各參數的意義。
📖 詳細說明請參考：YOLOv8 模型訓練

🔹 YOLOv8 訓練進階設定

你將學到：內建資料增強參數的調整時機（Mosaic、fliplr、HSV）、防止過擬合的設定（Early Stopping、weight_decay、dropout），以及整合所有設定的完整訓練範例。
這篇是訓練篇的延伸，幫你把「能跑」進化到「訓練得好」。
📖 詳細說明請參考：YOLOv8 訓練進階設定

🔹 YOLOv8 訓練結果分析

你將學到：讀懂 mAP、Precision、Recall、F1 曲線，解讀混淆矩陣，判斷是否需要補資料或調整參數。
訓練完不等於結束，這篇幫你判斷「模型夠不夠好」和「下一步該怎麼做」。
📖 詳細說明請參考：YOLOv8 訓練結果分析

🔹 YOLOv8 推論與匯出

你將學到：用訓練好的模型對圖片、影片、攝影機進行推論，匯出成 ONNX 接入 OpenCV，或匯出成 TensorRT 部署到 GPU 伺服器。
這是整個 YOLO 系列的最後一站，從訓練結果到實際可用的部署格式。
📖 詳細說明請參考：YOLOv8 推論與匯出

🔹 YOLOv8 常見問題 Q&A

你將學到：新增類別的兩種策略、遷移學習 Fine-tuning 做法、資料量與比例建議、訓練中斷續訓、模型選擇、效果診斷，以及用現有模型做預標籤、公開模型資源下載。
整理學完整個 YOLO 流程後最常出現的問題，以 Q&A 形式逐一解答，適合遇到問題時快速查閱。
📖 詳細說明請參考：YOLOv8 常見問題 Q&A

🎯 結語

如果前面的分類系列是「學會如何訓練模型的完整思路」，YOLO 系列就是「把這個思路用最有效率的方式實作在物件偵測任務上」。

下一篇是 YOLOv8 介紹與環境安裝，從 Ultralytics 套件的安裝開始，跑通第一次推論。

註：以上參考了
Ultralytics YOLOv8 官方文件
 YOLO 論文 — You Only Look Once