Heuristic:Kornia Kornia Morphology Engine Selection
| Knowledge Sources | |
|---|---|
| Domains | Optimization, Image_Processing |
| Last Updated | 2026-02-09 15:00 GMT |
Overview
Morphological operations offer two compute engines: convolution (faster, less memory) vs unfold (more numerically stable), selectable via the `engine` parameter.
Description
Kornia's morphological operations (dilation, erosion, opening, closing, gradient, top_hat, bottom_hat) support two computation engines. The convolution engine uses standard PyTorch convolution operations, which are faster and consume less memory due to GPU-optimized kernels. The unfold engine uses `torch.nn.functional.unfold` to explicitly extract neighborhoods, which provides more numerically stable results at the cost of higher memory usage and slower execution. The choice is exposed as an `engine` parameter defaulting to `"unfold"`.
Usage
Choose the engine based on your priority: use `engine="convolution"` for production workloads where speed and memory efficiency matter, and `engine="unfold"` (the default) for research or debugging where numerical precision is paramount. If you observe subtle differences in morphological results between CPU and GPU, try switching to `"unfold"` for consistency.
The Insight (Rule of Thumb)
- Action: Set `engine="convolution"` in morphological operations for faster, memory-efficient computation.
- Value: Default is `engine="unfold"` for maximum numerical stability.
- Trade-off: Convolution is faster and uses less memory; unfold is more numerically stable. Results may differ slightly between engines.
Reasoning
The convolution engine maps morphological operations to standard conv2d calls, leveraging cuDNN on GPU. However, the mapping involves representing max/min pooling as convolutions with specific padding schemes, which can introduce edge effects or rounding differences. The unfold engine explicitly materializes the local neighborhoods, applies the structuring element, and reduces, which is mathematically exact but requires allocating the unfolded tensor (significantly more memory for large kernels).
Code Evidence
Engine parameter documentation from `kornia/morphology/morphology.py:62`:
engine: convolution is faster and less memory hungry, and unfold is more stable numerically
Function signature with engine parameter from `kornia/morphology/morphology.py:32-41`:
def dilation(
tensor: torch.Tensor,
kernel: torch.Tensor,
structuring_element: Optional[torch.Tensor] = None,
origin: Optional[List[int]] = None,
border_type: str = "geodesic",
border_value: float = 0.0,
max_val: float = 1e4,
engine: str = "unfold",
) -> torch.Tensor:
This same pattern appears in all seven morphological operations: `dilation`, `erosion`, `opening`, `closing`, `gradient`, `top_hat`, `bottom_hat`.