opencv-python

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

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

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

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

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)