Smoothing#

Smoothing Module#

This module provides simple 2D smoothing functions for gridded surfaces used in influencer games visualizations. It includes Gaussian and median filtering capabilities with automatic fallback to NumPy-based implementations when SciPy is not available.

The module is designed to work with the InflGame package and supports smoothing of heat maps, contour plots, and other 2D surface visualizations to improve visual quality and reduce noise.

Dependencies:#

  • numpy (required)

  • scipy.ndimage (optional, recommended for better performance)

Usage:#

The smoothing functions accept and return NumPy arrays of shape \((H, W)\) where \(H\) is height and \(W\) is width. When SciPy is available, optimized filters are used; otherwise, NumPy-based fallback implementations are employed.

Example:#

from InflGame.utils.smoothing import gaussian_smooth, median_smooth
import numpy as np

# Create a noisy 2D surface
surface = np.random.rand(100, 100)

# Apply Gaussian smoothing
smoothed = gaussian_smooth(surface, sigma=2.0)

# Apply median filtering
filtered = median_smooth(surface, kernel_size=5)

# Check if SciPy is available
from InflGame.utils.smoothing import try_import_scipy
has_scipy = try_import_scipy()

Functions

InflGame.utils.smoothing.gaussian_smooth(surface, sigma=1.0, truncate=4.0)#

Apply Gaussian smoothing to a 2D surface.

Performs a Gaussian blur operation on a 2D grid using either SciPy’s optimized implementation or a NumPy-based separable convolution fallback. The Gaussian kernel is defined by its standard deviation (sigma) and is truncated beyond a specified number of standard deviations.

Parameters:
surfacenp.ndarray

2D numpy array of shape \((H, W)\) representing the surface to smooth.

sigmafloat, optional

Standard deviation for the Gaussian kernel, measured in grid units, by default 1.0. Larger values produce more smoothing.

truncatefloat, optional

Truncate the Gaussian filter at this many standard deviations, by default 4.0. The filter radius will be int(truncate * sigma + 0.5).

Returns:
np.ndarray

Smoothed 2D numpy array of the same shape as input.

Raises:
ValueError

If surface is not a 2D array.

Notes

When SciPy is available, this function uses scipy.ndimage.gaussian_filter for optimal performance. Otherwise, it falls back to a separable 1D Gaussian kernel convolution using NumPy, which is slower but produces similar results.

The Gaussian kernel is defined as:

\[G(x) = \frac{1}{\sqrt{2\pi\sigma^2}} \exp\left(-\frac{x^2}{2\sigma^2}\right)\]

Examples

>>> import numpy as np
>>> surface = np.random.rand(50, 50)
>>> smoothed = gaussian_smooth(surface, sigma=2.0)
>>> smoothed.shape
(50, 50)
InflGame.utils.smoothing.median_smooth(surface, kernel_size=3)#

Apply median filtering to a 2D surface.

Performs median filtering on a 2D grid using either SciPy’s optimized implementation or a NumPy-based sliding window fallback. Median filtering is particularly effective at removing salt-and-pepper noise while preserving edges.

Parameters:
surfacenp.ndarray

2D numpy array of shape \((H, W)\) representing the surface to filter.

kernel_sizeint, optional

Size of the square filtering window, by default 3. Must be an odd positive integer. Larger kernel sizes provide more aggressive noise reduction but may blur fine details.

Returns:
np.ndarray

Filtered 2D numpy array of the same shape as input.

Raises:
ValueError

If surface is not a 2D array.

ValueError

If kernel_size is not an odd positive integer.

Notes

When SciPy is available, this function uses scipy.ndimage.median_filter for optimal performance. The NumPy fallback uses edge-padded sliding windows and is significantly slower for large arrays but produces identical results.

The median operation for each pixel is computed over a \(k \times k\) window centered on that pixel, where \(k\) = kernel_size.

Examples

>>> import numpy as np
>>> surface = np.random.rand(50, 50)
>>> # Add some noise
>>> surface[10, 10] = 100
>>> surface[20, 20] = -100
>>> # Remove noise with median filter
>>> filtered = median_smooth(surface, kernel_size=5)
>>> filtered.shape
(50, 50)
InflGame.utils.smoothing.try_import_scipy()#

Check if SciPy is available in the current environment.

This function returns the availability status of SciPy’s ndimage module, which is used for optimized filtering operations. When SciPy is not available, the smoothing functions automatically fall back to NumPy-based implementations.

Returns:
bool

True if SciPy is available and can be imported, False otherwise.

Examples

>>> has_scipy = try_import_scipy()
>>> if has_scipy:
...     print("Using optimized SciPy filters")
... else:
...     print("Using NumPy fallback implementations")