> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opencv/opencv/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Bindings

> Install and use OpenCV with Python, including NumPy integration and idiomatic Python examples

## Overview

The OpenCV Python bindings provide a Pythonic interface to OpenCV's C++ API. The bindings are automatically generated and offer excellent performance while maintaining ease of use. All functions work seamlessly with NumPy arrays.

## Installation

### Using pip (Recommended)

The easiest way to install OpenCV for Python:

<CodeGroup>
  ```bash Standard Package theme={null}
  pip install opencv-python
  ```

  ```bash Full Package (with contrib modules) theme={null}
  pip install opencv-contrib-python
  ```

  ```bash Headless (no GUI) theme={null}
  pip install opencv-python-headless
  ```
</CodeGroup>

<Note>
  The `opencv-python` package includes prebuilt binaries for Windows, macOS, and Linux. No compilation required.
</Note>

### Version Requirements

* Python 3.6 or higher
* NumPy (automatically installed as a dependency)

### Building from Source

For custom builds or the latest development version:

```bash theme={null}
# Clone the repository
git clone https://github.com/opencv/opencv.git
cd opencv

# Create build directory
mkdir build && cd build

# Configure with Python support
cmake -DBUILD_opencv_python3=ON \
      -DPYTHON3_EXECUTABLE=$(which python3) \
      -DPYTHON3_NUMPY_INCLUDE_DIRS=$(python3 -c "import numpy; print(numpy.get_include())") \
      ..

# Build
make -j$(nproc)

# Install
sudo make install
```

## Quick Start

### Importing OpenCV

```python theme={null}
import cv2 as cv
import numpy as np
```

<Note>
  The module is imported as `cv2` for historical reasons. This naming convention is standard across all OpenCV Python code.
</Note>

### Verify Installation

```python theme={null}
import cv2 as cv

print(f"OpenCV version: {cv.__version__}")
print(f"NumPy version: {np.__version__}")

# Check available modules
print(cv.getBuildInformation())
```

## Core Concepts

### NumPy Integration

OpenCV images are represented as NumPy arrays:

```python theme={null}
import cv2 as cv
import numpy as np

# Load image as NumPy array
img = cv.imread('image.jpg')

print(f"Image shape: {img.shape}")  # (height, width, channels)
print(f"Data type: {img.dtype}")    # uint8
print(f"Image size: {img.size}")    # total pixels

# Create blank image
blank = np.zeros((480, 640, 3), dtype=np.uint8)

# All NumPy operations work on images
img_float = img.astype(np.float32) / 255.0
mean_color = np.mean(img, axis=(0, 1))
```

### Image Format: BGR vs RGB

<Warning>
  OpenCV uses BGR color order by default, not RGB. Convert when working with other libraries like Matplotlib or PIL.
</Warning>

```python theme={null}
import cv2 as cv
import matplotlib.pyplot as plt

# Read image (BGR format)
img_bgr = cv.imread('image.jpg')

# Convert to RGB for matplotlib
img_rgb = cv.cvtColor(img_bgr, cv.COLOR_BGR2RGB)

plt.imshow(img_rgb)
plt.show()
```

## Code Examples

### Reading and Writing Images

```python theme={null}
import cv2 as cv

# Read image
img = cv.imread('input.jpg')

if img is None:
    print('Could not open or find the image')
    exit(0)

# Read in grayscale
gray = cv.imread('input.jpg', cv.IMREAD_GRAYSCALE)

# Save image
cv.imwrite('output.jpg', img)

# Save with quality settings (JPEG)
cv.imwrite('output.jpg', img, [cv.IMWRITE_JPEG_QUALITY, 90])
```

### Video Capture and Display

```python theme={null}
import cv2 as cv

# Open webcam
cap = cv.VideoCapture(0)

# Or open video file
# cap = cv.VideoCapture('video.mp4')

if not cap.isOpened():
    print("Cannot open camera")
    exit()

while True:
    # Capture frame-by-frame
    ret, frame = cap.read()
    
    if not ret:
        print("Can't receive frame. Exiting...")
        break
    
    # Convert to grayscale
    gray = cv.cvtColor(frame, cv.COLOR_BGR2GRAY)
    
    # Display the frame
    cv.imshow('frame', gray)
    
    # Press 'q' to quit
    if cv.waitKey(1) == ord('q'):
        break

# Release resources
cap.release()
cv.destroyAllWindows()
```

### Face Detection

```python theme={null}
import cv2 as cv
import numpy as np

def detect_faces(img, cascade):
    """Detect faces in an image using Haar Cascade."""
    gray = cv.cvtColor(img, cv.COLOR_BGR2GRAY)
    gray = cv.equalizeHist(gray)
    
    faces = cascade.detectMultiScale(
        gray,
        scaleFactor=1.3,
        minNeighbors=4,
        minSize=(30, 30),
        flags=cv.CASCADE_SCALE_IMAGE
    )
    
    return faces

def draw_faces(img, faces):
    """Draw rectangles around detected faces."""
    for (x, y, w, h) in faces:
        cv.rectangle(img, (x, y), (x+w, y+h), (0, 255, 0), 2)

# Load cascade classifier
cascade = cv.CascadeClassifier(
    cv.samples.findFile('haarcascades/haarcascade_frontalface_alt.xml')
)

# Open camera
cam = cv.VideoCapture(0)

while True:
    ret, img = cam.read()
    if not ret:
        break
    
    faces = detect_faces(img, cascade)
    draw_faces(img, faces)
    
    cv.imshow('facedetect', img)
    
    if cv.waitKey(5) == 27:  # ESC key
        break

cam.release()
cv.destroyAllWindows()
```

### Image Processing Pipeline

```python theme={null}
import cv2 as cv
import numpy as np

# Read image
src = cv.imread('input.jpg')

# Convert to grayscale
gray = cv.cvtColor(src, cv.COLOR_BGR2GRAY)

# Apply Gaussian blur
blurred = cv.GaussianBlur(gray, (5, 5), 0)

# Edge detection
edges = cv.Canny(blurred, 50, 150)

# Find contours
contours, hierarchy = cv.findContours(
    edges, 
    cv.RETR_EXTERNAL, 
    cv.CHAIN_APPROX_SIMPLE
)

# Draw contours on original image
result = src.copy()
cv.drawContours(result, contours, -1, (0, 255, 0), 2)

# Save result
cv.imwrite('output.jpg', result)
```

### Histogram Calculation and Visualization

```python theme={null}
import cv2 as cv
import numpy as np
import matplotlib.pyplot as plt

# Load image
src = cv.imread('image.jpg')

# Split into color channels
bgr_planes = cv.split(src)

# Calculate histograms
histSize = 256
histRange = (0, 256)

b_hist = cv.calcHist(bgr_planes, [0], None, [histSize], histRange)
g_hist = cv.calcHist(bgr_planes, [1], None, [histSize], histRange)
r_hist = cv.calcHist(bgr_planes, [2], None, [histSize], histRange)

# Plot histograms
plt.figure(figsize=(10, 6))
plt.plot(b_hist, color='b', label='Blue')
plt.plot(g_hist, color='g', label='Green')
plt.plot(r_hist, color='r', label='Red')
plt.xlabel('Pixel Value')
plt.ylabel('Frequency')
plt.legend()
plt.show()
```

### Working with ROI (Region of Interest)

```python theme={null}
import cv2 as cv
import numpy as np

# Load image
img = cv.imread('image.jpg')

# Define ROI using NumPy slicing
height, width = img.shape[:2]
roi = img[100:300, 200:400]  # [y1:y2, x1:x2]

# Modify ROI
roi[:] = (0, 255, 0)  # Fill with green

# Copy ROI to another location
img[50:250, 450:650] = roi

# Create ROI mask
mask = np.zeros(img.shape[:2], dtype=np.uint8)
cv.circle(mask, (width//2, height//2), 100, 255, -1)

# Apply mask
masked_img = cv.bitwise_and(img, img, mask=mask)

cv.imshow('Result', masked_img)
cv.waitKey(0)
```

### Image Transformations

```python theme={null}
import cv2 as cv
import numpy as np

img = cv.imread('image.jpg')

# Resize
resized = cv.resize(img, (640, 480))
# Or scale by factor
scaled = cv.resize(img, None, fx=0.5, fy=0.5)

# Rotate
height, width = img.shape[:2]
center = (width // 2, height // 2)
angle = 45
scale = 1.0

rotation_matrix = cv.getRotationMatrix2D(center, angle, scale)
rotated = cv.warpAffine(img, rotation_matrix, (width, height))

# Flip
flipped_horizontal = cv.flip(img, 1)
flipped_vertical = cv.flip(img, 0)
flipped_both = cv.flip(img, -1)

# Crop using NumPy slicing
cropped = img[100:400, 200:500]
```

## Advanced Features

### Working with Multiple Images

<Tabs>
  <Tab title="Batch Processing">
    ```python theme={null}
    import cv2 as cv
    import glob

    # Process all images in a directory
    image_paths = glob.glob('images/*.jpg')

    for path in image_paths:
        img = cv.imread(path)
        
        # Apply processing
        gray = cv.cvtColor(img, cv.COLOR_BGR2GRAY)
        blurred = cv.GaussianBlur(gray, (5, 5), 0)
        
        # Save result
        output_path = path.replace('images/', 'output/')
        cv.imwrite(output_path, blurred)
    ```
  </Tab>

  <Tab title="Image Stacking">
    ```python theme={null}
    import cv2 as cv
    import numpy as np

    # Read multiple images
    img1 = cv.imread('image1.jpg')
    img2 = cv.imread('image2.jpg')
    img3 = cv.imread('image3.jpg')

    # Horizontal stack
    h_stack = np.hstack([img1, img2, img3])

    # Vertical stack
    v_stack = np.vstack([img1, img2, img3])

    # Grid layout
    row1 = np.hstack([img1, img2])
    row2 = np.hstack([img3, img1])
    grid = np.vstack([row1, row2])

    cv.imshow('Grid', grid)
    cv.waitKey(0)
    ```
  </Tab>
</Tabs>

### Performance Tips

```python theme={null}
import cv2 as cv
import numpy as np
import time

# Use optimized NumPy operations
img = cv.imread('large_image.jpg')

# Efficient: Vectorized operation
start = time.time()
result = img * 0.5
print(f"Vectorized: {time.time() - start:.4f}s")

# Inefficient: Loop over pixels (avoid this!)
start = time.time()
result = img.copy()
for i in range(img.shape[0]):
    for j in range(img.shape[1]):
        result[i, j] = img[i, j] * 0.5
print(f"Loop: {time.time() - start:.4f}s")

# Use in-place operations when possible
img *= 0.5  # Modifies img directly, no new array

# Pre-allocate arrays
output = np.empty_like(img)
cv.cvtColor(img, cv.COLOR_BGR2GRAY, dst=output[:,:,0])
```

## Package Structure

The Python bindings are organized to mirror the C++ API:

```python theme={null}
import cv2 as cv

# Core functionality
mat = cv.Mat()
version = cv.__version__

# Image processing
blurred = cv.GaussianBlur(img, (5, 5), 0)

# Video I/O
cap = cv.VideoCapture(0)

# Feature detection
orb = cv.ORB_create()

# DNN module
net = cv.dnn.readNet('model.onnx')

# Find sample data files
path = cv.samples.findFile('lena.jpg')
```

## Common Issues

<Warning>
  **AttributeError**: If you get "module 'cv2' has no attribute", make sure you're using the correct module name and that the feature is included in your OpenCV build.
</Warning>

### Virtual Environments

```bash theme={null}
# Create virtual environment
python -m venv opencv_env

# Activate
source opencv_env/bin/activate  # Linux/macOS
# or
opencv_env\Scripts\activate  # Windows

# Install OpenCV
pip install opencv-python
```

## Resources

* [OpenCV-Python Tutorials](https://docs.opencv.org/4.x/d6/d00/tutorial_py_root.html)
* [PyPI Package](https://pypi.org/project/opencv-python/)
* [Python API Reference](https://docs.opencv.org/4.x/d6/d00/tutorial_py_root.html)
* [Sample Code](https://github.com/opencv/opencv/tree/4.x/samples/python)

## Next Steps

* Learn about [Image Processing](/modules/imgproc) with Python
* Explore [Deep Learning with DNN](/modules/dnn) module
* Try [Video Analysis](/modules/video) examples