اگر می‌خواهید با چند خط کد یک عکس معمولی را بخوانید، خاکستری کنید، لبه‌هایش را دربیاورید و حتی چهره‌ها را داخلش پیدا کنید، دقیقاً همان چیزی که لازم دارید کتابخانه OpenCV است. در این آموزش از نصب تمیز بسته تا اولین برنامه‌ی قابل اجرا قدم‌به‌قدم جلو می‌رویم و در پایان یک اسکریپت کامل تشخیص چهره می‌سازیم که هم روی عکس و هم روی ویدیو کار می‌کند. همه کدها کوتاه و بدون وابستگی اضافه‌اند و فقط به پایتون نیاز دارند.

OpenCV در پایتون چیست و چه کاری انجام می‌دهد؟

OpenCV (متن‌باز) یک کتابخانه متن‌باز به زبان ++C است که صدها الگوریتم پردازش تصویر و ویدیو را در اختیار پایتون و چند زبان دیگر می‌گذارد؛ از خواندن فایل و فیلترگذاری تا تشخیص چهره، شمارش ورود و ردیابی حرکت. بسته رسمی روی PyPI با نام opencv-python منتشر می‌شود و با pip در چند ثانیه نصب می‌شود. ادامه مقاله را بخوانید تا کدهای کامل را ببینید.

فهرست مطالب

پیش‌نیازها و نصب OpenCV در سه گام
اولین برنامه OpenCV؛ خواندن، نمایش و ذخیره عکس
خط لوله پردازش تصویر؛ خاکستری، فیلتر گاوسی و لبه‌یابی کنی
تشخیص چهره با OpenCV در ده خط کد
کدام روش تشخیص را انتخاب کنیم؟ (جدول مقایسه)
کاربردهای واقعی OpenCV در پروژه‌های هوش مصنوعی
نکات امنیتی و حریم خصوصی در پردازش تصویر
اشتباهات و خطاهای رایج در OpenCV
سوالات متداول
جمع‌بندی؛ چک‌لیست عملی

پیش‌نیازها و نصب OpenCV در سه گام

پیش‌نیاز شما فقط یک نصب پایتون نسخه ۳٫۹ به بالا و یک محیط مجازی تمیز است. هر چهار بسته‌ی خانواده‌ی OpenCV از فضای نام یکسان cv2 استفاده می‌کنند، پس نصب همزمان دو یا چند نسخه از آن‌ها، محیط را خراب می‌کند. همیشه فقط یکی را انتخاب کنید.

گام اول — انتخاب بسته درست

برای کار روی لپ‌تاپ یا دسکتاپ که می‌خواهید پنجره‌ی نمایش تصویر داشته باشید، بسته اصلی opencv-python کافی است. اگر پروژه‌تان روی سرور، داکر یا محیط بدون گرافیک اجرا می‌شود و از cv2.imshow استفاده نمی‌کنید، نسخه opencv-python-headless را نصب کنید؛ سبک‌تر است و وابستگی‌های سنگین گرافیکی ندارد. اگر به ماژول‌های اضافه (مثل الگوریتم‌های تجربی xfeatures2d یا برخی ابزارهای OCR) نیاز دارید، نسخه opencv-contrib-python را بردارید.

بسته	مناسب برای	نمایش پنجره تصویر
opencv-python	دسکتاپ، لپ‌تاپ، یادگیری	بله
opencv-python-headless	سرور، داکر، ربات، اینترنت اشیا	خیر
opencv-contrib-python	پروژه‌های پژوهشی و الگوریتم‌های اضافه	بله
opencv-contrib-python-headless	سرور با الگوریتم‌های contrib	خیر

گام دوم — نصب در یک محیط مجازی تمیز

نسخه‌ای که در زمان نگارش این مقاله با pip install opencv-python نصب می‌شود، 4.12.0.88 است و برای پایتون ۳٫۹ به بالا به numpy نسخه ۲ یا بالاتر نیاز دارد. کد زیر را در ترمینال اجرا کنید:

python -m venv .venv
# ویندوز:
.venv\Scripts\activate
# مک و لینوکس:
source .venv/bin/activate
pip install --upgrade pip
pip install "opencv-python==4.12.0.88"

اگر روی سرور یا داخل داکر کار می‌کنید، به‌جای دستور آخر بنویسید pip install opencv-python-headless. نکته مهم: کتابخانه‌ی هسته‌ی OpenCV در ژوئن ۲۰۲۶ به نسخه ۵٫۰٫۰ رسید، اما در زمان نگارش این مقاله هنوز بسته‌ی opencv-python نسخه ۵ روی PyPI منتشر نشده است؛ پس نصب از pip همچنان به خط ۴٫x می‌رسد.

گام سوم — تأیید نصب

قبل از نوشتن اولین برنامه، مطمئن شوید نصب سالم بوده است:

import cv2
print(cv2.__version__)

اگر عددی مثل 4.12.0 چاپ شد، همه چیز آماده است. عدد نسخه را یادداشت کنید؛ در بخش خطاهای رایج دوباره به آن برمی‌گردیم.

اولین برنامه OpenCV؛ خواندن، نمایش و ذخیره عکس

در OpenCV تصویر یک آرایه‌ی عددی است و رنگ‌ها برخلاف اکثر کتابخانه‌ها به ترتیب آبی، سبز، قرمز (BGR) خوانده می‌شوند. همین یک نکته، رایج‌ترین دلیل گم شدن رنگ‌ها در خروجی است. کد زیر یک عکس را می‌خواند، پنجره نمایش می‌دهد و با کلید q آن را می‌بندد:

import cv2

img = cv2.imread("photo.jpg")
if img is None:
    raise FileNotFoundError("عکس پیدا نشد؛ مسیر را بررسی کنید")

print("ابعاد تصویر:", img.shape)  # (ارتفاع, عرض, کانال)

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

# تغییر اندازه به نصف ابعاد
small = cv2.resize(img, None, fx=0.5, fy=0.5)
cv2.imwrite("small.jpg", small)

تابع cv2.waitKey(0) برنامه را تا فشردن یک کلید نگه می‌دارد و اگر آن را صفر بگذارید، فقط ۱ میلی‌ثانیه صبر می‌کند. برای ویدیو از عدد بزرگ‌تر مثل ۲۵ استفاده کنید تا نرخ فریم طبیعی شود. توجه کنید که imread مسیر را به صورت متن لاتین تفسیر می‌کند و روی ویندوز با مسیرهای فارسی به مشکل می‌خورد؛ راه‌حل مطمئن این است:

import numpy as np

data = np.fromfile("تصاویر/منظره.jpg", dtype=np.uint8)
img = cv2.imdecode(data, cv2.IMREAD_COLOR)

در این حالت فایل را با NumPy می‌خوانید و خود OpenCV آن را به تصویر تبدیل می‌کند، پس نام فارسی فایل هم مشکلی ایجاد نمی‌کند. برای ذخیره‌سازی هم معادل فارسی‌پسند وجود دارد:

ok = cv2.imencode("خروجی.jpg", img)[1]
ok.tofile("خروجی.jpg")

خط لوله پردازش تصویر؛ خاکستری، فیلتر گاوسی و لبه‌یابی کنی

تقریباً هر پروژه‌ی بینایی ماشین با یک خط لوله‌ی ساده شروع می‌شود: تصویر رنگی را به خاکستری تبدیل کن، نویز را با فیلتر گاوسی بگیر و بعد لبه‌ها را با الگوریتم کنی بیرون بکش. سه مرحله در یک اسکریپت کوتاه:

import cv2

gray = cv2.imread("photo.jpg", cv2.IMREAD_GRAYSCALE)
blur = cv2.GaussianBlur(gray, (5, 5), 0)
edges = cv2.Canny(blur, 80, 160)

cv2.imwrite("edges.jpg", edges)
print("تعداد پیکسل لبه:", edges.sum() // 255)

تبدیل تصویر به خاکستری

پارامتر cv2.IMREAD_GRAYSCALE تصویر را مستقیم به یک کانال خاکستری تبدیل می‌کند و حجم پردازش را کم می‌کند. اگر می‌خواهید روی تصویرِ از قبل خوانده‌شده کار کنید، از cv2.cvtColor(img, cv2.COLOR_BGR2GRAY) استفاده کنید.

فیلتر گاوسی برای حذف نویز

قبل از لبه‌یابی، تصویر را تار می‌کنیم تا نویز به‌جای لبه، خودش را به‌عنوان لبه معرفی نکند. عدد اول اندازه کرنل است و باید فرد باشد؛ عدد صفر برای انحراف معیار یعنی «خود OpenCV محاسبه کند» که تقریباً همیشه بهترین انتخاب است.

لبه‌یابی با الگوریتم کنی

الگوریتم کنی دو آستانه می‌گیرد: پیکسل‌هایی که اختلافشان از آستانه پایین کمتر است پس‌زمینه‌اند و پیکسل‌هایی که از آستانه بالا بیشترند هسته لبه. چون آستانه پایین و آستانه بالا معمولاً نسبت ۱ به ۲ انتخاب می‌شوند، مقدار 80, 160 مثال خوبی است. اگر لبه‌ها خیلی کم یا خیلی زیاد شدند، این دو عدد را بالا و پایین کنید؛ این ساده‌ترین ابزار تنظیم کیفیت خروجی است.

خروجی لبه‌یابی یک تصویر سیاه‌وسفید است که فقط پیکسل‌های لبه در آن مقدار ۲۵۵ دارند و بقیه صفر. برای همین محاسبه‌ی تعداد لبه‌ها در کد بالا با تقسیم بر ۲۵۵ انجام می‌شود.

تشخیص چهره با OpenCV در ده خط کد

OpenCV به‌صورت پیش‌فرض مدل‌های آماده‌ی تشخیص چهره را همراه بسته نصب می‌کند و مسیر آن‌ها با cv2.data.haarcascades در دسترس است. کد زیر هر چهره را پیدا می‌کند و دور آن کادر می‌کشد:

import cv2

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

img = cv2.imread("group.jpg")
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)

faces = face_cascade.detectMultiScale(
    gray, scaleFactor=1.1, minNeighbors=5, minSize=(40, 40)
)

for (x, y, w, h) in faces:
    cv2.rectangle(img, (x, y), (x + w, y + h), (0, 255, 0), 2)

print("تعداد چهره‌ها:", len(faces))
cv2.imwrite("faces.jpg", img)

سه پارامتر این تابع کلید کار شما هستند: scaleFactor سرعت و دقت را تنظیم می‌کند (هر چه کمتر، دقیق‌تر و کندتر)، minNeighbors تعیین می‌کند چند ناحیه‌ی مشابه کنار هم لازم است تا یک چهره واقعی شمرده شود و minSize کوچک‌ترین اندازه‌ی قابل قبول را تعیین می‌کند. چهره‌های کوچک در عکس‌های گروهی را معمولاً با کوچک کردن scaleFactor به ۱٫۰۵ و پایین آوردن minNeighbors به ۳ پیدا می‌کنید، به قیمت کند شدن.

کدام روش تشخیص را انتخاب کنیم؟

تشخیص چهره فقط یک راه ندارد. جدول زیر سه مسیر رایج را با معیارهای روشن مقایسه می‌کند تا بدانید کدام را بردارید.

روش	سرعت	دقت	نیاز به مدل جدا	مناسب برای
Haar Cascade	خیلی بالا	متوسط	خیر (همراه بسته)	یادگیری، وب‌کم، دوربین قدیمی
شبکه عصبی عمیق (DNN/SSD)	متوسط	بالا	بله (فایل ONNX/caffemodel)	محصول واقعی با چند چهره
YOLO	بالا روی GPU	خیلی بالا	بله (وزن‌های مدل)	چند شیء همزمان در ویدیو

قانون ساده این است: برای یادگیری و نمونه اول با Haar Cascade شروع کنید چون هیچ فایل مدلی نمی‌خواهد؛ وقتی پروژه وارد فاز محصول شد و نویز نتیجه آزارتان داد، سراغ مدل عمیق بروید. توجه کنید که Haar روی تصویر کوچک، تاریک یا با چرخش زیاد سرِ قاعده ضعیف عمل می‌کند.

کاربردهای واقعی OpenCV در پروژه‌های هوش مصنوعی

OpenCV معمولاً نقطه‌ی شروع هر پروژه‌ی بینایی است: پیش‌پردازش ورودی مدل، کاهش نویز و تغییر اندازه پیش از اینکه تصویر به یک مدل یادگیری ماشین برسد. کاربردهای پرتکرار شامل شمارش خودکوچه‌ها در خط تولید، تشخیص پلاک خوان، اسکن و بایگانی اسناد، کنترل کیفیت روی برد الکترونیکی و تشخیص حرکت در دوربین مداربسته است.

یک مثال کاربردی و آماده‌ی اجرا، شمارش زنده‌ی افراد در ویدیوی وب‌کم است. کد زیر هر فریم را پردازش می‌کند و فقط تعداد را روی تصویر می‌نویسد:

import cv2

cascade = cv2.CascadeClassifier(
    cv2.data.haarcascades + "haarcascade_frontalface_default.xml"
)
cap = cv2.VideoCapture(0)

while True:
    ok, frame = cap.read()
    if not ok:
        break
    gray = cv2.cvtColor(frame, cv2.COLOR_BGR2GRAY)
    faces = cascade.detectMultiScale(gray, 1.1, 5)
    cv2.putText(frame, f"People: {len(faces)}", (20, 40),
                cv2.FONT_HERSHEY_SIMPLEX, 1, (0, 255, 0), 2)
    cv2.imshow("live", frame)
    if cv2.waitKey(1) & 0xFF == ord("q"):
        break

cap.release()
cv2.destroyAllWindows()

همین خط لوله‌ی سبک استدلال، در مرورگرهای جدید هوش مصنوعی و مدل‌های چندوجهی هم استفاده می‌شود؛ اگر می‌خواهید بدانید پردازش تصویر چطور به سخت‌افزار و سرمایه‌گذاری عظیم وابسته شده، خبر خرید World Labs توسط AMD به مبلغ ۸٫۲ میلیارد دلار را بخوانید.

نکات امنیتی و حریم خصوصی در پردازش تصویر

تصویر، داده‌ی شخصی است. اگر در پروژه‌تان چهره‌ی افراد را تشخیص می‌دهید، رزومه می‌کنید یا مسیر رفت‌وآمد می‌سازید، چهره و ردپای حرکتی به‌عنوان داده‌ی زیستی حساس شناخته می‌شود و نگهداری و اشتراک آن می‌تواند مسئله‌ی حقوقی جدی باشد. چند قاعده‌ی عملی:

تصاویر خام را روی سرور ذخیره نکنید؛ اگر لازم است، رمزنگاری و دوره‌ی نگهداری مشخص تعریف کنید.
مجوز روشن کاربران را برای پردازش تصویر بگیرید و در رابط کاربری نشان دهید چه چیزی تحلیل می‌شود.
مدل‌های تشخیص چهره را روی تصاویر حساس به‌صورت محلی اجرا کنید تا داده از دستگاه خارج نشود.
نتیجه‌ی الگوریتم‌های کلاسیک را قطعی فرض نکنید؛ خطای تشخیص در قالب‌های کنترلی می‌تواند تصمیم اشتباه بسازد.

چارچوب‌های قانونی این حساسیت را جدی گرفته‌اند؛ برای نمونه، مقررات برچسب‌گذاری محتوای هوش مصنوعی در اروپا، بحث برچسب‌زدن به محتوای تولیدشده را جدی گرفته است. جزئیات را در مقاله‌ی قانون هوش مصنوعی اروپا و برچسب‌گذاری محتوای AI بخوانید.

اشتباهات و خطاهای رایج در OpenCV

پنج مشکل پرتکرار تازه‌کارها و راه‌حل هر کدام:

۱) خطای could not find a matching version

معمولاً نسخه‌ی پایتون شما خارج از محدوده‌ی پشتیبانی است یا یک نسخه‌ی قدیمی pip دارید. اول pip را به‌روزرسانی کنید و بعد نصب را بدون قفل کردن نسخه تکرار کنید.

۲) خطای ModuleNotFoundError: No module named cv2

یا محیط فعال نیست، یا بسته در محیط دیگری نصب شده است. با python -m pip install opencv-python نصب کنید تا دقیقاً در همان مفسری نصب شود که اجرا می‌کنید، و مسیر را با python -c "import sys; print(sys.executable)" چک کنید.

۳) تصویر None برمی‌گردد و imwrite چیزی نمی‌نویسد

مسیر اشتباه است، پسوند پشتیبانی نمی‌شود یا فایل قفل است. همیشه نتیجه‌ی imread را بررسی کنید و برای فایل فارسی از روش np.fromfile و imdecode استفاده کنید.

۴) خطای DLL load failed در ویندوز

نسخه‌های قدیمی Visual C++ Redistributable یا نصب همزمان چند نسخه‌ی OpenCV باعثش می‌شود. بسته‌های اضافه را با pip uninstall پاک کنید، فقط یکی را نگه دارید و در صورت نیاز بسته‌ی به‌روزرسانی مایکروسافت را نصب کنید.

۵) پنجره تصویر باز نمی‌شود یا کد در محیط بدون نمایشگر گیر می‌کند

در سرور و داکر تابع‌های نمایش کار نمی‌کنند. بسته‌ی headless را نصب کنید و نتیجه را با cv2.imwrite روی دیسک ذخیره کنید؛ یا از یک سرور نمایشگر مجازی استفاده کنید.

سوالات متداول

آیا OpenCV برای یادگیری ماشین هم مناسب است؟

برای پیش‌پردازش بله، برای آموزش مدل نه. OpenCV ابزار آماده‌سازی داده است: خواندن، تغییر اندازه، نرمال‌سازی و افزایش داده. برای ساخت و آموزش شبکه عصبی باید سراغ PyTorch یا TensorFlow رفت و خروجی پردازش‌شده را به آن‌ها داد. ترکیب این دو، مسیر استاندارد پروژه‌های بینایی ماشین است.

تفاوت opencv-python و opencv-contrib-python چیست؟

بسته‌ی اصلی فقط ماژول‌های اصلی را دارد. بسته‌ی contrib همان کد به‌علاوه‌ی ماژول‌های آزمایشی و الگوریتم‌های غیراستاندارد است. اگر به الگوریتم خاصی نیاز دارید که در مستندات رسمی نیست، contrib را نصب کنید؛ در غیر این صورت بسته‌ی اصلی سبک‌تر و کم‌دردسرتر است. هرگز هر دو را با هم نصب نکنید.

آیا OpenCV رایگان است و برای پروژه تجاری هم مناسب است؟

بله. بسته‌ی پایتون تحت مجوز MIT و خود کتابخانه‌ی OpenCV تحت مجوز Apache 2.0 منتشر می‌شود، پس استفاده در محصول تجاری و تغییر در آن آزاد است. تنها استثنا الگوریتم‌های غیرآزاد و دارای پتنت است که در نسخه‌های رسمی ارائه نمی‌شوند.

چرا تشخیص چهره روی بعضی عکس‌ها شکست می‌خورد؟

مدل‌های Haar روی چهره‌های روبه‌رو، روشن و نسبتاً بزرگ آموزش دیده‌اند. نور کم، زاویه‌ی زیاد، عینک ضخیم، کلاه و عکس‌های کم‌کیفیت باعث خطا می‌شوند. اول تصویر را خاکستری و کمی تار کنید، اندازه‌ی چهره‌ها را با minSize پایین بیاورید و در صورت نیاز به مدل عمیق مهاجرت کنید.

آیا نسخه ۵ هم آمده است و کدهای قدیمی را می‌شکند؟

نسخه ۵٫۰٫۰ از کتابخانه‌ی هسته در ژوئن ۲۰۲۶ منتشر شد و راهنمای مهاجرت رسمی هم دارد، اما بسته‌ی پایتون روی PyPI هنوز در خط ۴٫x است. کدهای این آموزش برای خط ۴ نوشته شده‌اند و همان‌ها را نصب می‌کنید؛ برای مهاجرت به نسخه ۵ ابتدا راهنمای مهاجرت OpenCV را بخوانید و سپس تست‌های پروژه را اجرا کنید.

جمع‌بندی؛ چک‌لیست عملی

برای اینکه امروز نتیجه بگیرید، این ترتیب را جلو بروید:

یک محیط مجازی تازه بسازید و فقط یکی از بسته‌های خانواده‌ی OpenCV را در آن نصب کنید.
با یک اسکریپت چهارخطی، نسخه را چاپ کنید و یک عکس را بخوانید، تغییر اندازه دهید و ذخیره کنید.
خط لوله‌ی خاکستری، فیلتر گاوسی و کنی را پیاده کنید و با بازی با دو آستانه، کیفیت لبه‌ها را تنظیم کنید.
مدل Haar Cascade را روی یک عکس گروهی اجرا کنید و سه پارامتر تشخیص را کم‌کم بهینه کنید.
همین کد را روی ویدیو یا وب‌کم اجرا کنید و سرعت واقعی را اندازه بگیرید.
پیش از افزودن داده‌های واقعی، تکلیف حریم خصوصی و مجوز کاربران را روشن کنید.

همین امروز یک عکس از دوربین گوشی‌تان بردارید و با همان ده خط تشخیص چهره، اولین پروژه‌ی بینایی ماشین خودتان را اجرا کنید. وقتی ابزار را در عمل لمس کرده باشید، یادگیری مسیرهای سخت‌تر مثل مدل‌های عمیق هم ساده‌تر می‌شود.

آموزش OpenCV در پایتون؛ پردازش تصویر و تشخیص چهره از صفر