LearnOpenCV.ir

مقدمه‌ای بر OpenCV

نصب OpenCV برای پایتون با pip

۴ دقیقه مطالعهOpenCV 5.xبه‌روزرسانی:

این راهنمای شروع سریع، روش توصیه‌شده را برای اکثر کاربران جهت تهیه OpenCV در پایتون نشان می‌دهد: نصب از PyPI با استفاده از pip. همچنین محیط‌های مجازی (virtual environments)، نکات مربوط به سیستم‌عامل‌ها و عیب‌یابی‌های رایج را شرح می‌دهد. اگر به جایگزین‌های خاص سیستم‌عامل (بسته‌های سیستمی یا کامپایل از سورس) نیاز دارید، به صفحات سیستم‌عامل که در زیر پیوند داده شده‌اند مراجعه کنید، اما این موارد برای استفاده معمول از پایتون لازم نیستند.

شروع سریع#

# 1) Create and activate a virtual environment (recommended)
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# 2) Upgrade pip tooling
python -m pip install --upgrade pip setuptools wheel

# 3) Install OpenCV from PyPI (choose ONE)
pip install opencv-python          # main package (most users)
# or
pip install opencv-contrib-python  # + extra modules (contrib)
# or
pip install opencv-python-headless # no GUI/backends (servers/CI)
# or
pip install opencv-contrib-python-headless # no GUI/backends with extra modules (servers/CI)

برنامه کوچک سلام دنیا (Tiny hello-world)#

import cv2 as cv
import numpy as np

print("OpenCV:", cv.__version__)
img = np.zeros((120, 400, 3), dtype=np.uint8)
cv.putText(img, "OpenCV OK", (10, 80), cv.FONT_HERSHEY_SIMPLEX, 2, (255,255,255), 3)
# If you installed a non-headless build, you can display a window:
# cv.imshow("hello", img); cv.waitKey(0)
# Always safe (headless or not): save to file
cv.imwrite("hello.png", img)

محیط‌های مجازی و محیط‌های توسعه یکپارچه (IDEs)#

استفاده از یک محیط مجازی وابستگی‌های پروژه را ایزوله نگه می‌دارد. ابزارهایی که محیط‌ها را ایجاد یا فعال می‌کنند عبارتند از:

  • venv (داخلی پایتون) و virtualenv
  • محیط‌های Conda
  • محیط‌های توسعه یکپارچه (مانند VS Code و PyCharm) که ممکن است به طور خودکار برای هر فضای کاری یک محیط مجازی ایجاد و فعال کنند

اگر عملیات ایمپورت داخل یک IDE با شکست مواجه شد، بررسی کنید که مفسر (interpreter) انتخاب‌شده توسط IDE با محیطی که OpenCV را در آن نصب کرده‌اید مطابقت داشته باشد.

نکات سیستم‌عامل#

  • Linux: ممکن است پایتون پیش‌فرض شما python3 باشد. از دستورات python3 -m venv .venv و ... python3 -m pip استفاده کنید. اگر نمی‌توانید از یک محیط مجازی استفاده کنید، سوئیچ pip --user بسته را در دایرکتوری خانگی شما نصب می‌کند: python3 -m pip install --user opencv-python.
  • Windows: پایتون را از [python.org] یا از طریق winget install Python.Python.3 نصب کنید. مطمئن شوید که گزینه “Add python to PATH” فعال باشد، یا از گزینه “Open in terminal” در IDE خود استفاده کنید که مفسر صحیح را به طور خودکار انتخاب می‌کند.
  • macOS: از python3 سیستمی یا یک نسخه مدیریت‌شده (Homebrew یا Python.org) استفاده کنید. همیشه ترجیحاً از یک محیط مجازی استفاده کنید.
  • Raspberry Pi / بردهای ARM: چرخ‌ها (Wheels) از پیش ساخته شده ممکن است برای برخی ترکیبات Pi OS / Python وجود نداشته باشند. به بخش عیب‌یابی در زیر مراجعه کنید.

انتخاب نگارش PyPI#

  • opencv-python: ماژول‌های هسته OpenCV همراه با رابط کاربری گرافیکی و بک‌اندها
  • opencv-contrib-python: علاوه بر هسته، شامل ماژول‌های توسعه‌یافته (contrib) است
  • opencv-python-headless: بدون رابط کاربری/بک‌اند (ایده‌آل برای سرورها/کانتینرها/CI)
  • opencv-contrib-python-headless: ماژول‌های اضافی contrib به همراه headless

در هر محیط دقیقاً یکی از این نگارش‌ها را نصب کنید.

عیب‌یابی#

لطفاً ابتدا فایل README پروژه opencv-python را مطالعه کنید.

ابزار Pip در حال تلاش برای کامپایل از سورس است علائم: مرحله بیلد بسیار طولانی، خطاهای CMake، خطاهای کامپایلر. راه‌حل‌ها:

  • ابزارهای بیلد را ارتقا دهید: python -m pip install --upgrade pip setuptools wheel
  • اطمینان حاصل کنید که نسخه پایتون شما توسط بسته انتخابی پشتیبانی می‌شود.
  • اگر روی یک پلتفرم یا بیلد غیرمعمول پایتون هستید، به یک پایتون پشتیبانی‌شده تغییر وضعیت دهید یا نگارش متفاوتی را امتحان کنید (headless در مقابل non-headless).

خطای “No matching distribution found” یا “Unsupported wheel”

  • نسخه پایتون خود را تأیید کنید (مثلاً با python -V). چرخی را انتخاب کنید که از آن نسخه پشتیبانی کند (چرخ‌های manylinux/macOS/Windows در PyPI نسخه‌های خاصی از پایتون را هدف قرار می‌دهند).
  • یک محیط مجازی تازه با نسخه اصلی و پایدار پایتون (مثلاً در حال حاضر 3.10–3.12) ایجاد کرده و مجدداً نصب کنید.

Raspberry Pi / بردهای ARM

  • چرخ‌ها ممکن است از نسخه‌های جدید Python/Pi OS عقب‌تر باشند. ابتدا opencv-python-headless را امتحان کنید. در صورت عدم دسترسی، بسته‌های سیستمی را برای بخش‌های دوربین/رابط کاربری در نظر بگیرید، یا طبق صفحه سیستم‌عامل لینک‌شده در زیر، از سورس کامپایل کنید.

ایمپورت در ترمینال کار می‌کند اما در IDE با خطا مواجه می‌شود

  • محیط توسعه IDE از مفسر متفاوتی استفاده می‌کند. در تنظیمات مفسر IDE خود، دقیقاً همان محیط مجازی را انتخاب کنید.

بسته‌های سیستمی یا بیلد از سورس چطور؟#

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

همچنین ببینید#