changedetectionio/processors/image_ssim_diff/README.md
Visual/screenshot change detection using ultra-fast image comparison algorithms.
This processor uses OpenCV by default for screenshot comparison, providing 50-100x faster performance compared to the previous SSIM implementation while still detecting meaningful visual changes.
MAX_DIFF_HEIGHT/MAX_DIFF_WIDTH)The processor uses OpenCV's cv2.absdiff() for ultra-fast pixel-level comparison:
# Convert to grayscale
gray_from = cv2.cvtColor(image_from, cv2.COLOR_RGB2GRAY)
gray_to = cv2.cvtColor(image_to, cv2.COLOR_RGB2GRAY)
# Apply Gaussian blur (reduces noise, controlled by OPENCV_BLUR_SIGMA env var)
gray_from = cv2.GaussianBlur(gray_from, (0, 0), sigma=0.8)
gray_to = cv2.GaussianBlur(gray_to, (0, 0), sigma=0.8)
# Calculate absolute difference
diff = cv2.absdiff(gray_from, gray_to)
# Apply threshold (default: 30)
_, thresh = cv2.threshold(diff, threshold, 255, cv2.THRESH_BINARY)
# Count changed pixels
change_percentage = (changed_pixels / total_pixels) * 100
For users who need better anti-aliasing detection (especially for text-heavy screenshots), pixelmatch can be optionally installed:
pip install pybind11-pixelmatch>=0.1.3
Note: Pixelmatch uses a C++17 implementation via pybind11 and may have build issues on some platforms (particularly Alpine/musl systems with symbolic link security restrictions). The application will automatically fall back to OpenCV if pixelmatch is not available.
To use pixelmatch instead of OpenCV, set the environment variable:
COMPARISON_METHOD=pixelmatch
# Comparison method (opencv or pixelmatch)
COMPARISON_METHOD=opencv # Default
# OpenCV threshold (0-255, lower = more sensitive)
COMPARISON_THRESHOLD_OPENCV=30 # Default
# Pixelmatch threshold (0-100, mapped to 0-1 scale)
COMPARISON_THRESHOLD_PIXELMATCH=10 # Default
# Gaussian blur sigma for OpenCV (0 = no blur, higher = more blur)
OPENCV_BLUR_SIGMA=0.8 # Default
# Minimum change percentage to trigger detection
OPENCV_MIN_CHANGE_PERCENT=0.1 # Default (0.1%)
PIXELMATCH_MIN_CHANGE_PERCENT=0.1 # Default
# Diff visualization image size limits (pixels)
MAX_DIFF_HEIGHT=8000 # Default
MAX_DIFF_WIDTH=900 # Default
Use the "Include filters" field with CSS selectors or XPath to compare only specific page regions:
.content-area
//div[@id='main']
The processor will automatically crop both screenshots to the bounding box of the first matched element.
opencv-python-headless>=4.8.0.76 - Fast image comparisonPillow (PIL) - Image loading and manipulationnumpy - Array operationspybind11-pixelmatch>=0.1.3 - Alternative comparison method with anti-aliasing detection# Explicit cleanup for long-running processes
img.close() # Close PIL Images
buffer.close() # Close BytesIO buffers
del large_array # Mark numpy arrays for GC
The Gaussian blur reduces sensitivity to:
Increase OPENCV_BLUR_SIGMA to make comparison more tolerant of these differences.
| Feature | OpenCV | Pixelmatch | SSIM (old) |
|---|---|---|---|
| Speed | 50-100x faster | 10-20x faster | Baseline |
| Anti-aliasing | Via blur | Built-in detection | Built-in |
| Text sensitivity | High | Medium (AA-aware) | Medium |
| Dependencies | opencv-python-headless | pybind11-pixelmatch + C++ compiler | scikit-image |
| Alpine/musl support | ✅ Yes | ⚠️ Build issues | ✅ Yes |
| Memory usage | Low | Low | High |
| Best for | General use, max speed | Text-heavy screenshots | Deprecated |
If you're upgrading from the old SSIM-based processor:
OPENCV_BLUR_SIGMA if you're getting false positivesPotential features for future consideration: