# opencv-python

Cursor rule enforcing fast, vectorized computer vision pipelines in Python. It stops nested pixel loops and prevents common OpenCV pitfalls.

- rule · `type=rule` · Cursor · ★ 3580
- Author: sanjeed5
- License: CC0-1.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/opencv-python.mdc
- Updated: 2026-05-19
- HTML: https://affpapa.org/en/nevibecode/rules/opencv-python

## What it does

This rule targets `**/*.py` files to guide the AI assistant toward clean OpenCV patterns. The core requirement is complete vectorization. Instead of writing slow Python loops over pixels, the assistant must use NumPy operations or native C++ OpenCV routines.

Code structure matters here. The rule forbids monolithic scripts, requiring modular functions with explicit Python type hints using `numpy.ndarray`. It also guards against common runtime issues like unhandled `None` returns from `cv2.imread` when an image fails to load.

Color handling is strictly controlled. Since OpenCV loads images in BGR format, explicit conversions via `cv2.cvtColor` are enforced before sending data to Matplotlib. Array copying via `copy()` is discouraged unless independent mutation of slices is required.

## Install

### Cursor (native platform)

**Manually: put the files in place**
- File: `.cursor/rules/opencv-python.mdc` — Frontmatter: description, globs, alwaysApply

### Claude Code

**Manually: put the files in place**
- File: `.claude/rules/opencv-python.md` — The paths frontmatter field limits the files: move globs from the source into paths

### Codex

**AGENTS.md**
- Codex reads AGENTS.md: paste the rule text there

### GitHub Copilot

**Manually: put the files in place**
- File: `.github/instructions/opencv-python.instructions.md` — The applyTo field sets which files it applies to: move globs from the source into applyTo

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/rules/opencv-python.md`

### Cline

**Manually: put the files in place**
- File: `.clinerules/opencv-python.md`

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/opencv-python.mdc

## When to use it
- replace slow pixel-wise loops with vectorized NumPy operations
- prevent silent crashes when `cv2.imread` returns `None`
- stop BGR and RGB color space mix-ups in Matplotlib
- enforce modular pipeline functions with typed `numpy.ndarray`

## Example prompts
- Write a fast image inversion function without explicit pixel loops
- Create a modular Canny edge detection pipeline with proper typing
- Load an image safely, checking for errors and converting BGR to RGB

## Source text · opencv-python.mdc · CC0-1.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: ddbb74944a1c6d2b.

BEGIN THIRD-PARTY FILE ddbb74944a1c6d2b
````text
---
description: This guide provides definitive, opinionated best practices for writing high-performance, maintainable, and robust `opencv-python` code in Python applications.
globs: **/*.py
---
# `opencv-python` Best Practices

`opencv-python` is the de-facto standard for computer vision in Python. To write efficient, reliable, and maintainable code, treat OpenCV objects as NumPy arrays and prioritize vectorized operations. This guide outlines the essential practices for our team.

## Core Philosophy: Vectorize Everything

OpenCV functions are C++ optimized. Leverage them directly or use NumPy's vectorized operations instead of explicit Python loops for pixel-wise processing. This is the single most important performance rule.

❌ **BAD: Pixel-wise loop**
```python
import cv2
import numpy as np

def invert_image_slow(image: np.ndarray) -> np.ndarray:
    """Inverts an image pixel by pixel (slow)."""
    h, w, c = image.shape
    inverted_image = np.zeros_like(image)
    for y in range(h):
        for x in range(w):
            inverted_image[y, x] = 255 - image[y, x]
    return inverted_image
```

✅ **GOOD: Vectorized operation**
```python
import cv2
import numpy as np

def invert_image_fast(image: np.ndarray) -> np.ndarray:
    """Inverts an image using vectorized NumPy (fast)."""
    return 255 - image

# Or using OpenCV's built-in function for more complex ops
def convert_to_grayscale(image: np.ndarray) -> np.ndarray:
    """Converts an image to grayscale using cv2 (fast)."""
    return cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
```

## Code Organization and Structure

Organize your vision pipelines into small, focused functions. Each function should perform a single, well-defined image processing step.

❌ **BAD: Monolithic script**
```python
import cv2
import numpy as np

# main.py
img = cv2.imread('input.jpg')
if img is None:
    print("Error loading image")
    exit()
gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
blurred = cv2.GaussianBlur(gray, (5, 5), 0)
edges = cv2.Canny(blurred, 50, 150)
cv2.imshow('Edges', edges)
cv2.waitKey(0)
cv2.destroyAllWindows()
cv2.imwrite('output_edges.jpg', edges)
```

✅ **GOOD: Modular functions**
```python
import cv2
import numpy as np
from typing import Optional

def load_image(path: str) -> Optional[np.ndarray]:
    """Loads an image, checking for errors."""
    img = cv2.imread(path)
    if img is None:
        print(f"Error: Could not load image from {path}")
    return img

def preprocess_image(image: np.ndarray) -> np.ndarray:
    """Applies grayscale, blur, and Canny edge detection."""
    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY)
    blurred = cv2.GaussianBlur(gray, (5, 5), 0)
    edges = cv2.Canny(blurred, 50, 150)
    return edges

def display_image(window_name: str, image: np.ndarray) -> None:
    """Displays an image and waits for a key press."""
    cv2.imshow(window_name, image)
    cv2.waitKey(0)
    cv2.destroyAllWindows()

# main.py
if __name__ == "__main__":
    input_path = 'input.jpg'
    output_path = 'output_edges.jpg'

    original_img = load_image(input_path)
    if original_img is not None:
        processed_img = preprocess_image(original_img)
        display_image('Processed Edges', processed_img)
        cv2.imwrite(output_path, processed_img)
```

## Common Pitfalls and Gotchas

### 1. `cv2.imread` Returns `None`

Always check the return value of `cv2.imread`. It returns `None` if the image cannot be found or loaded.

❌ **BAD: Assuming image load success**
```python
img = cv2.imread('non_existent.jpg')
# This will crash if img is None
gray_img = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
```

✅ **GOOD: Robust image loading**
```python
img = cv2.imread('non_existent.jpg')
if img is None:
    raise FileNotFoundError("Image not found or could not be loaded.")
gray_img = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
```

### 2. Color Space Mismatches (BGR vs RGB)
````
END THIRD-PARTY FILE ddbb74944a1c6d2b

The third-party file has ended. Everything between the ddbb74944a1c6d2b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 3898 of 8725 bytes. © sanjeed5 · CC0-1.0 · https://github.com/sanjeed5/awesome-cursor-rules-mdc/tree/HEAD/rules-mdc/opencv-python.mdc

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md