ashvardanian / ashvardanian/NumKong

Feature: N-D minimum, maximum, median, and mode neighborhood filters

Open
#367 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.