簡介這份資源面向機器視覺與人工智能方向的初學(xué)者及進階開發(fā)者圍繞OCR、OpenCV與深度學(xué)習(xí)構(gòu)建了一套可運行的人臉、視頻與文字檢測識別項目合集幫助讀者在真實代碼中理解從環(huán)境搭建到模型推理的完整鏈路。包內(nèi)共128個文件以png截圖、md教程文檔、py腳本為主另含gif演示、hdf5與h5模型權(quán)重、ttc字體及json配置壓縮包約35.56MB兼顧代碼、素材與說明。內(nèi)容覆蓋人臉檢測與識別、輪廓標(biāo)識、頭像合成、數(shù)字化妝、性別與七種表情識別、視頻對象提取、圖片修復(fù)與自動上色、眼動追蹤及換臉等實踐方向并配套OpenCV環(huán)境搭建、Tesseract OCR文字識別、Dlib與OpenCV雙版本檢測、Ubuntu與Windows源更換、OpenCV中文支持等教程。已有362人學(xué)習(xí)適合按模塊檢索、對照復(fù)現(xiàn)并積累排錯經(jīng)驗。1. 從一張模糊的門禁抓拍說起OCR、OpenCV 和人臉識別怎么串成一條流水線小區(qū)門禁機拍到一張側(cè)臉光照不均、運動模糊后臺卻要在 300 毫秒內(nèi)完成人臉比對同時把訪客登記表上的姓名、身份證號用 OCR 抽出來入庫。這個場景里機器視覺負責(zé)“看清”人工智能負責(zé)“看懂”O(jiān)penCV 是那套趁手的圖像處理工具箱OCR 和人臉識別則是兩條并行的識別支路。很多人把這幾樣?xùn)|西當(dāng)成四個獨立項目分別學(xué)結(jié)果真到落地時發(fā)現(xiàn)攝像頭取流、預(yù)處理、模型推理、結(jié)果結(jié)構(gòu)化任何一環(huán)掉鏈子整條線就廢了。這篇筆記面向想用 Python 把 OpenCV、OCR、人臉檢測識別串成一個可跑通項目的工程師從環(huán)境裝起到參數(shù)怎么調(diào)、坑在哪一步步拆開講。適合有基礎(chǔ) Python 語法、想往機器視覺方向落地的讀者也適合正在做人工智能大作業(yè)或畢設(shè)選題的人拿來當(dāng)骨架。2. 環(huán)境與選型OpenCV、OCR 引擎、人臉模型到底怎么搭2.1 三個組件的職責(zé)邊界先劃清動手之前必須把分工想明白否則后面會寫出“用 OCR 去識別人臉”這種荒唐代碼。OpenCV 的定位是圖像 I/O 和傳統(tǒng)圖像處理讀視頻流、縮放、灰度化、直方圖均衡、邊緣檢測、透視變換它不負責(zé)“認識”圖像內(nèi)容。OCR 引擎負責(zé)把圖像里的文字區(qū)域轉(zhuǎn)成字符串常見的有 Tesseract、PaddleOCR、ddddocr 這幾類。人臉識別負責(zé)檢測人臉框并對齊再提取特征向量做比對常見方案是 OpenCV 自帶的 Haar/LBP 級聯(lián)做檢測或者用 ONNX 格式的 ArcFace 類模型做特征提取。選型上我的習(xí)慣是檢測用 OpenCV 的 DNN 模塊加載輕量人臉檢測模型識別用 ArcFace 系列OCR 中文場景優(yōu)先 PaddleOCR純數(shù)字驗證碼場景用 ddddocr 更省事。熱搜里常出現(xiàn)的modulenotfounderror: no module named opencv和opencv安裝成功卻找不到cv2九成是虛擬環(huán)境沒激活或者 pip 裝到了系統(tǒng) Python 而 IDE 用的是另一個解釋器這個后面避坑章節(jié)細說。2.2 用 conda 建一個干凈環(huán)境并裝齊依賴不要直接在系統(tǒng) Python 上 pip install版本沖突會讓你懷疑人生。下面這套命令我用了很多次穩(wěn)定。# 創(chuàng)建獨立環(huán)境Python 版本選 3.9 或 3.10兼容性最好 conda create -n vision_ocr python3.10 -y conda activate vision_ocr # 裝 OpenCV用 opencv-python 而非 contrib 版除非你要用 SIFT 等專利算法 pip install opencv-python4.8.1.78 pip install opencv-contrib-python4.8.1.78 # OCR 引擎PaddleOCR 中文強ddddocr 輕量 pip install paddlepaddle paddleocr pip install ddddocr # 人臉識別相關(guān) pip install onnxruntime numpy pillow邏輯說明opencv-python和opencv-contrib-python不要同時裝兩個不同版本會互相覆蓋導(dǎo)致cv2.error。PaddleOCR 首次運行會自動下載模型權(quán)重需要網(wǎng)絡(luò)通暢。onnxruntime用來跑 ArcFace 的 ONNX 模型比直接裝 PyTorch 輕量得多。參數(shù)說明OpenCV 版本我鎖在 4.8.x因為 4.4.0 在某些 Windows 編譯版本上有已知的cv2.error路徑問題熱搜里那條opencv(4.4.0) c:\users\appveyor\...報錯就是典型。Python 選 3.10 是因為 PaddleOCR 對 3.11 的支持還不穩(wěn)。2.3 驗證環(huán)境是否真的通了裝完別急著寫業(yè)務(wù)代碼先跑一段最小驗證確認 cv2 能導(dǎo)入、能讀圖、OCR 能出字。import cv2 import numpy as np # 打印版本確認不是裝了個假的 print(OpenCV version:, cv2.__version__) # 造一張純色圖驗證基本讀寫 img np.zeros((200, 400, 3), dtypenp.uint8) img[:] (255, 255, 255) cv2.putText(img, TEST 123, (50, 100), cv2.FONT_HERSHEY_SIMPLEX, 1.5, (0, 0, 0), 3) cv2.imwrite(test.png, img) # 讀回來確認 back cv2.imread(test.png) print(Image shape:, back.shape if back is not None else read failed)邏輯說明這段代碼不依賴任何外部圖片自己造圖自己讀能排除“圖片路徑錯”的干擾。如果cv2.__version__打印出來但imread返回 None說明 OpenCV 的編解碼后端有問題重裝opencv-python通常能解決。參數(shù)說明np.zeros的 dtype 必須是uint8OpenCV 只認這個。putText的坐標(biāo)是左上角為原點別寫成數(shù)學(xué)坐標(biāo)系。3. 人臉檢測與識別從 Haar 到 ArcFace 的落地路徑3.1 檢測環(huán)節(jié)為什么我最終放棄了 HaarHaar 級聯(lián)是 OpenCV 自帶、零依賴、跑得飛快但它的誤檢率在復(fù)雜背景下高得離譜側(cè)臉和遮擋基本沒戲。熱搜里easyai人臉識別、arcface人臉識別這些詞說明大家已經(jīng)在往深度學(xué)習(xí)方案遷移。我的做法是檢測用 OpenCV DNN 加載一個輕量 SSD 或 YuNet 模型識別用 ArcFace 提特征。YuNet 是 OpenCV 官方在 4.5.4 之后集成的輕量人臉檢測模型模型文件只有幾百 KBCPU 上也能跑到實時。下面是從視頻流里抓人臉框的最小實現(xiàn)。import cv2 # 加載 YuNet 模型模型文件需自行下載 onnx detector cv2.FaceDetectorYN.create( modelface_detection_yunet_2023mar.onnx, config, input_size(320, 320), score_threshold0.7, # 置信度閾值低于此值的人臉丟棄 nms_threshold0.3, # 非極大值抑制閾值控制重疊框合并 top_k5000 ) cap cv2.VideoCapture(0) # 0 表示默認攝像頭 while True: ret, frame cap.read() if not ret: break h, w frame.shape[:2] detector.setInputSize((w, h)) # 必須和實際幀尺寸一致 _, faces detector.detect(frame) if faces is not None: for face in faces: x, y, fw, fh face[:4].astype(int) cv2.rectangle(frame, (x, y), (x fw, y fh), (0, 255, 0), 2) cv2.imshow(face, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()邏輯說明setInputSize必須在每幀檢測前調(diào)用且要和幀的實際寬高一致否則檢測框坐標(biāo)會整體偏移這是新手最容易翻車的地方。score_threshold調(diào)高減少誤檢但會漏檢0.7 是室內(nèi)場景的折中值。參數(shù)說明nms_threshold越小重疊的人臉框合并越激進多人臉靠近時容易漏掉一個0.3 到 0.4 之間比較穩(wěn)。top_k是保留的最大候選框數(shù)一般用不到改。3.2 識別環(huán)節(jié)ArcFace 特征提取與比對檢測到人臉后需要做對齊再提特征。ArcFace 的輸入通常是 112x112 對齊后的人臉。對齊依賴五點關(guān)鍵點雙眼、鼻尖、嘴角YuNet 的輸出里正好帶了這五個點可以直接用。import cv2 import numpy as np import onnxruntime as ort # 加載 ArcFace ONNX 模型 session ort.InferenceSession(arcface_r100.onnx, providers[CPUExecutionProvider]) input_name session.get_inputs()[0].name def align_face(img, landmarks): # landmarks 是 5 個點的坐標(biāo)做相似變換對齊到標(biāo)準(zhǔn)位置 dst np.array([[38.2946, 51.6963], [73.5318, 51.5014], [56.0252, 71.7366], [41.5493, 92.3655], [70.7299, 92.2041]], dtypenp.float32) src np.array(landmarks, dtypenp.float32).reshape(5, 2) M, _ cv2.estimateAffinePartial2D(src, dst) return cv2.warpAffine(img, M, (112, 112)) def get_embedding(face_img): # 歸一化到 [-1, 1]ArcFace 的標(biāo)準(zhǔn)預(yù)處理 blob cv2.dnn.blobFromImage(face_img, 1.0 / 128, (112, 112), (127.5, 127.5, 127.5), swapRBTrue) emb session.run(None, {input_name: blob})[0] # L2 歸一化方便用余弦相似度比對 return emb / np.linalg.norm(emb) # 比對余弦相似度大于閾值判定為同一人 def cosine_sim(a, b): return float(np.dot(a, b.T))邏輯說明estimateAffinePartial2D做的是相似變換只含旋轉(zhuǎn)、縮放、平移不含剪切這對人臉對齊足夠。blobFromImage里的swapRBTrue是因為 OpenCV 讀進來是 BGR而模型訓(xùn)練時用的是 RGB。參數(shù)說明ArcFace 的相似度閾值同一人一般大于 0.5不同人低于 0.3中間地帶需要根據(jù)業(yè)務(wù)調(diào)整。門禁場景寧可誤拒不可誤認閾值可以設(shè)到 0.6。3.3 把檢測和識別串成一條完整鏈路單獨跑通檢測和識別后串起來才是項目。下面這段把攝像頭、檢測、對齊、特征提取、比對串成一條線并維護一個簡單的人臉庫。import cv2 import numpy as np import onnxruntime as ort import pickle import os # 初始化檢測器和識別器 detector cv2.FaceDetectorYN.create(face_detection_yunet_2023mar.onnx, , (320, 320)) session ort.InferenceSession(arcface_r100.onnx, providers[CPUExecutionProvider]) input_name session.get_inputs()[0].name # 人臉庫{姓名: 特征向量} DB_PATH face_db.pkl face_db pickle.load(open(DB_PATH, rb)) if os.path.exists(DB_PATH) else {} def extract(frame, face): x, y, w, h face[:4].astype(int) landmarks face[4:14].reshape(5, 2) aligned align_face(frame, landmarks) return get_embedding(aligned) cap cv2.VideoCapture(0) while True: ret, frame cap.read() if not ret: break h, w frame.shape[:2] detector.setInputSize((w, h)) _, faces detector.detect(frame) if faces is not None: for face in faces: emb extract(frame, face) name, best unknown, 0.0 for db_name, db_emb in face_db.items(): sim cosine_sim(emb, db_emb) if sim best: best, name sim, db_name if best 0.5: name unknown x, y, fw, fh face[:4].astype(int) cv2.rectangle(frame, (x, y), (x fw, y fh), (0, 255, 0), 2) cv2.putText(frame, f{name} {best:.2f}, (x, y - 10), cv2.FONT_HERSHEY_SIMPLEX, 0.8, (0, 255, 0), 2) cv2.imshow(pipeline, frame) if cv2.waitKey(1) 0xFF ord(q): break cap.release() cv2.destroyAllWindows()邏輯說明人臉庫用 pickle 存簡單夠用。生產(chǎn)環(huán)境應(yīng)該換成向量數(shù)據(jù)庫但做項目演示 pickle 完全夠。best 0.5判定為陌生人這個閾值要結(jié)合你的實際數(shù)據(jù)調(diào)。參數(shù)說明face[4:14]是 YuNet 輸出的五個關(guān)鍵點順序是右眼、左眼、鼻尖、右嘴角、左嘴角和 ArcFace 標(biāo)準(zhǔn)模板的順序要對應(yīng)上順序錯了對齊就廢了。4. OCR 文字識別從截圖到結(jié)構(gòu)化字段的完整流程4.1 OCR 引擎選型PaddleOCR 和 ddddocr 各管一攤熱搜里php ocr識別驗證碼、c# ocr pdf、java使用百度ocr識別上傳合同文件這些場景本質(zhì)是兩類需求一類是通用文檔文字提取一類是特定格式的驗證碼或票據(jù)。我的分工是通用中文文檔、表格、票據(jù)用 PaddleOCR它的檢測識別方向分類三件套開箱即用純數(shù)字字母驗證碼用 ddddocr它專門為這個場景訓(xùn)練準(zhǔn)確率比通用引擎高一大截。PaddleOCR 的調(diào)用極其簡單但首次運行會下載模型網(wǎng)絡(luò)不好會卡住。下面是最小可用代碼。from paddleocr import PaddleOCR # use_angle_clsTrue 開啟方向分類處理倒置文字 # langch 中文模型英文場景改 en 更快 ocr PaddleOCR(use_angle_clsTrue, langch, show_logFalse) result ocr.ocr(invoice.png, clsTrue) # result 結(jié)構(gòu)[[ [box, (text, confidence)], ... ]] for line in result[0]: box, (text, conf) line print(f文字: {text}, 置信度: {conf:.3f}, 位置: {box})邏輯說明ocr.ocr返回的是嵌套列表第一層是圖片支持多圖第二層是文本行。每行包含四點坐標(biāo)框、識別文字、置信度。show_logFalse關(guān)掉 Paddle 的冗余日志輸出干凈很多。參數(shù)說明use_angle_clsTrue會多跑一個方向分類模型速度慢約 20%但能處理旋轉(zhuǎn)文字票據(jù)場景建議開。lang參數(shù)決定識別模型中文用ch純英文用en速度更快。4.2 用 OpenCV 做 OCR 前的預(yù)處理OCR 引擎不是萬能的輸入圖像質(zhì)量差識別率斷崖下跌。熱搜里opencv圖像處理項目、opencv識別物體說明大家已經(jīng)在用 OpenCV 做前處理。我常用的三板斧是灰度化、自適應(yīng)二值化、形態(tài)學(xué)去噪。import cv2 import numpy as np def preprocess_for_ocr(img_path): img cv2.imread(img_path) gray cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) # 自適應(yīng)二值化應(yīng)對光照不均 binary cv2.adaptiveThreshold( gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 31, 10 ) # 開運算去噪點閉運算連接斷裂筆畫 kernel np.ones((2, 2), np.uint8) opened cv2.morphologyEx(binary, cv2.MORPH_OPEN, kernel) closed cv2.morphologyEx(opened, cv2.MORPH_CLOSE, kernel) return closed processed preprocess_for_ocr(invoice.png) cv2.imwrite(processed.png, processed)邏輯說明adaptiveThreshold的 blockSize 必須是奇數(shù)31 適合 A4 掃描件小圖要調(diào)小。開運算去掉孤立噪點閉運算把斷開的筆畫連上這兩個順序不能反。參數(shù)說明C值是從均值里減去的常數(shù)值越大二值化越激進文字容易斷值越小背景噪點越多。10 是掃描件的常用值手機拍照場景可以調(diào)到 15。4.3 從 OCR 結(jié)果里抽結(jié)構(gòu)化字段OCR 出來是一堆文本行業(yè)務(wù)要的是“姓名、金額、日期”這些字段。熱搜里java使用百度ocr識別上傳合同文件時讀取收入、單位、時間等關(guān)鍵字段就是這個需求。我的做法是用正則匹配加關(guān)鍵詞定位。import re def extract_fields(ocr_result): fields {name: None, amount: None, date: None} full_text .join([line[1][0] for line in ocr_result[0]]) # 金額匹配 ￥ 或 元 前后的數(shù)字 amount_match re.search(r[￥]?\s*(\d[\.,]\d{2})\s*元?, full_text) if amount_match: fields[amount] amount_match.group(1).replace(,, ) # 日期匹配 2024-01-01 或 2024年1月1日 date_match re.search(r(\d{4})[-年/](\d{1,2})[-月/](\d{1,2}), full_text) if date_match: fields[date] f{date_match.group(1)}-{date_match.group(2)}-{date_match.group(3)} # 姓名定位姓名關(guān)鍵詞后的 2-4 個中文字 name_match re.search(r姓名[:]?\s*([\u4e00-\u9fa5]{2,4}), full_text) if name_match: fields[name] name_match.group(1) return fields邏輯說明先把所有文本行拼成一個長字符串再做正則匹配比逐行匹配更穩(wěn)因為 OCR 可能把“姓名”和值分到兩行。[\u4e00-\u9fa5]是中文字符的 Unicode 范圍。參數(shù)說明金額正則里的[\.,]兼容逗號和小數(shù)點兩種分隔符。日期正則的[-年/]兼容三種常見格式。姓名限定 2 到 4 個字太長會誤匹配到地址。5. 避坑與排查那些讓我加班到凌晨的報錯5.1 cv2 導(dǎo)入失敗但明明裝了現(xiàn)象import cv2報ModuleNotFoundError: No module named opencv但pip list里能看到 opencv-python。原因IDE 用的解釋器和 pip 裝包的解釋器不是同一個或者虛擬環(huán)境沒激活。熱搜里opencv安裝成功卻找不到cv2就是這個。解決在代碼里打印import sys; print(sys.executable)看實際用的 Python 路徑然后用這個路徑對應(yīng)的 pip 重裝。conda 環(huán)境要先conda activate。5.2 OpenCV 讀視頻流卡頓或花屏現(xiàn)象cap.read()返回的幀花屏或者幀率極低。原因攝像頭默認分辨率太高或者解碼后端不匹配。熱搜里opencv 2.4.9 for linux這類老版本問題更多。解決顯式設(shè)置分辨率和后端。cap.set(cv2.CAP_PROP_FRAME_WIDTH, 640)和cap.set(cv2.CAP_PROP_FRAME_HEIGHT, 480)后端用cv2.VideoCapture(0, cv2.CAP_DSHOW)在 Windows 上更穩(wěn)。5.3 OCR 識別不了韓文或小語種現(xiàn)象PaddleOCR 對韓文、日文識別率極低熱搜里以下ocr代碼識別不了韓文就是這個。原因默認加載的是中文模型不包含韓文字符集。解決PaddleOCR 支持多語言初始化時langkorean或langjapan但模型需要單獨下載。如果只是偶爾用可以換 Tesseract 并裝對應(yīng)語言包。5.4 人臉檢測框整體偏移現(xiàn)象檢測框畫出來偏到人臉左上角或右下角。原因setInputSize沒設(shè)或者設(shè)的尺寸和實際幀不一致。YuNet 默認輸入是 320x320直接喂 640x480 的幀就會偏。解決每幀檢測前調(diào)用detector.setInputSize((w, h))w 和 h 從frame.shape取。5.5 ddddocr 未安裝或版本沖突現(xiàn)象ModuleNotFoundError: No module named ddddocr或者裝了但 import 報 onnxruntime 相關(guān)錯誤。原因ddddocr 依賴特定版本的 onnxruntime和 ArcFace 用的版本可能沖突。解決給 ddddocr 單獨建一個環(huán)境或者用pip install ddddocr --no-deps再手動裝兼容的 onnxruntime。熱搜里ddddocr 未安裝多半是網(wǎng)絡(luò)問題導(dǎo)致 pip 沒裝完。6. 進階技巧用 OpenCV 的 solvePnP 做頭部姿態(tài)估計人臉識別跑通后如果想判斷用戶是不是在“正視屏幕”可以加一步頭部姿態(tài)估計。熱搜里opencv的函數(shù)solvepnp正好是這個用途。原理是用人臉的幾個 3D 模型點和 2D 圖像點做對應(yīng)解出旋轉(zhuǎn)向量再轉(zhuǎn)成歐拉角。import cv2 import numpy as np # 3D 人臉模型點通用人臉比例單位任意 model_points np.array([ (0.0, 0.0, 0.0), # 鼻尖 (0.0, -63.6, -12.5), # 下巴 (-43.3, 32.7, -26.0), # 左眼左角 (43.3, 32.7, -26.0), # 右眼右角 (-28.9, -28.9, -24.1), # 左嘴角 (28.9, -28.9, -24.1) # 右嘴角 ], dtypenp.float64) def estimate_head_pose(landmarks_2d, img_size): # landmarks_2d 是 6 個點的圖像坐標(biāo) focal_length img_size[1] center (img_size[1] / 2, img_size[0] / 2) camera_matrix np.array([ [focal_length, 0, center[0]], [0, focal_length, center[1]], [0, 0, 1] ], dtypenp.float64) dist_coeffs np.zeros((4, 1)) # 假設(shè)無畸變 success, rot_vec, trans_vec cv2.solvePnP( model_points, landmarks_2d, camera_matrix, dist_coeffs, flagscv2.SOLVEPNP_ITERATIVE ) if not success: return None # 旋轉(zhuǎn)向量轉(zhuǎn)旋轉(zhuǎn)矩陣再轉(zhuǎn)歐拉角 rot_mat, _ cv2.Rodrigues(rot_vec) angles, _, _, _, _, _ cv2.RQDecomp3x3(rot_mat) return angles # [pitch, yaw, roll]邏輯說明solvePnP解的是透視 n 點問題給定 3D 點和對應(yīng) 2D 點求相機外參。SOLVEPNP_ITERATIVE適合點數(shù)少的情況點數(shù)多可以用SOLVEPNP_EPNP更快。RQDecomp3x3把旋轉(zhuǎn)矩陣分解成歐拉角返回的 angles 里 yaw 超過 ±15 度基本可以判定為側(cè)臉。參數(shù)說明focal_length用圖像寬度近似精度要求高的話需要相機標(biāo)定。dist_coeffs全零是簡化處理廣角鏡頭必須做畸變校正否則角度偏差大。驗證方法讓測試者正對攝像頭看 yaw 是否接近 0頭往左偏yaw 應(yīng)該往一個方向變。如果方向反了檢查 model_points 的坐標(biāo)系定義。我自己的習(xí)慣是任何姿態(tài)估計的代碼寫完先拿自己的臉在攝像頭前轉(zhuǎn)一圈把三個角度的變化范圍記下來再定閾值。這比看論文里的公式快得多。希望幫到你。本文還有配套的精品資源點擊獲取