ashvardanian / ashvardanian/NumKong
Feature: N-D minimum, maximum, median, and mode neighborhood filters
- Dominant language
- C
- Stars
- 1.9k
- Forks
- 130
- Avg merge
- 18h 28m
- Merged PRs (30d)
- 3
Description
## Workload
Morphology, median denoising, and mode blur are neighborhood reductions:
- Dilation is a local maximum.
- Erosion is a local minimum.
- Opening and closing compose those two operations.
- Median blur selects the middle value in each neighborhood.
- Mode blur selects the most frequent value, with a deterministic tie rule.
AlbumentationsX currently uses `cv2.erode`, `dilate`, `morphologyEx`, and `medianBlur` on 2-D images. Batches and 3-D volumes require loops or another backend.
AlbumentationsX `ModeBlur` currently uses `np.pad`, `sliding_window_view`, a per-window `np.sort`, three full-size working arrays, and repeated `np.where` passes over every position in the local window. A specialized `uint8` neighborhood mode can use bounded-value histograms and avoid the materialized window tensor.
## Requested primitives
```python
nk.minimum_filter(x, size, axes=None, border_mode="constant", out=None)
nk.maximum_filter(x, size, axes=None, border_mode="constant", out=None)
nk.median_filter(x, size, axes=None, border_mode="reflect", out=None)
nk.mode_filter(x, size, axes=None, border_mode="reflect", out=None)
```
The exact API can use an explicit footprint instead of `size`.
## Initial scope
- Rectangular 2-D windows on `(..., H, W, C)`.
- Leading batch dimensions preserved.
- `uint8` and `float32` for min/max/median.
- `uint8` first for mode filtering.
- Odd window sizes, including sizes greater than five.
- Constant, replicate, reflect, and wrap borders.
- Optional `out=`.
- Channel counts greater than four and greater than 128 without shape reinterpretation.
- For mode ties, return the smallest value to match the current AlbumentationsX and SciPy behavior.
## Extensions
- Rectangular 3-D windows on `(..., D, H, W, C)`.
- Arbitrary binary footprints / structuring elements.
- Iteration count.
- Convenience `erode`, `dilate`, `open`, and `close` wrappers.
- Wider integer and floating-point mode filtering if a practical algorithm and workload justify them.
## Correctness and performance
Compare 2-D min/max/median results with OpenCV and N-D results with SciPy. Compare mode filtering with `scipy.ndimage` where available and the current AlbumentationsX sort-and-run-count implementation. Include kernel sizes 3, 5, 7, and 11; sparse and dense footprints; flat regions; impulses; multimodal ties; NaNs for floating inputs; C=1, C=9, and C=129; and windows that approach the input size.
Benchmark single images plus batches and volumes currently processed by a Python loop. For mode filtering, report peak memory as well as time because the current `sliding_window_view(...).reshape(...); np.sort(...)` path materializes data proportional to the window area.
Related tracker: #313.
Contributor guide
Research direction
Start by locating the requested nk.minimum_filter, nk.maximum_filter, nk.median_filter, and nk.mode_filter entry points and the current AlbumentationsX ModeBlur implementation. Compare 2-D results with OpenCV and N-D results with SciPy, including the listed sizes, borders, dtypes, channels, NaNs, footprints, and ties. Benchmark images, batches, and volumes while reporting mode-filter peak memory; done means the requested API and correctness and performance coverage are in place.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- c, numpy, python
- Domain
- computer-vision, performance
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100