Masked Blur

app.shared.masked_blur

Shared alpha-mask and Gaussian blur rendering used by preview and export.

`compute_blur_alpha_mask(frame_shape: tuple[int, ...], boxes: Sequence[BBoxViewModel], feather_radius: int = _FEATHER_RADIUS) -> np.ndarray`

Compute the combined interior-plus-outward-feather alpha mask.

PARAMETER	DESCRIPTION
`frame_shape`	Image shape beginning with `(height, width)`. TYPE: `tuple[int, ...]`
`boxes`	Bounding boxes whose interiors will be blurred. TYPE: `Sequence[BBoxViewModel]`
`feather_radius`	Outward feather distance in pixels. TYPE: `int` DEFAULT: `_FEATHER_RADIUS`

RETURNS	DESCRIPTION
`ndarray`	A float32 alpha mask of shape `(height, width)` with values from 0 to 1.

RAISES	DESCRIPTION
`ValueError`	If the frame shape or feather radius is invalid.

Note

Distance transform measures each outside pixel's distance to the union of box interiors. Alpha reaches zero at feather_radius; with the default value, the preview footprint includes the same 10-pixel outward zone as exported blur.

For outside distance \(d\) and feather radius \(r\), the mask uses

\[ u = \operatorname{clip}\!\left(1-\frac{d}{r},0,1\right),\qquad \alpha = \operatorname{smoothstep}(u)=u^2(3-2u). \]

Box interiors have \(\alpha=1\); alpha reaches zero at or beyond the feather radius.

Example

mask = compute_blur_alpha_mask(frame.shape, frame_boxes)

`apply_masked_blur(frame: np.ndarray, boxes: Sequence[BBoxViewModel], strength: float, feather_radius: int = _FEATHER_RADIUS) -> np.ndarray`

Blur the union of box interiors with a smooth outward alpha feather.

PARAMETER	DESCRIPTION
`frame`	RGB or BGR image to process. TYPE: `ndarray`
`boxes`	Bounding boxes to blur. TYPE: `Sequence[BBoxViewModel]`
`strength`	Requested Gaussian kernel width; converted to an odd width of at least three pixels. TYPE: `float`
`feather_radius`	Outward feather distance in pixels. TYPE: `int` DEFAULT: `_FEATHER_RADIUS`

RETURNS	DESCRIPTION
`ndarray`	The processed frame. The input frame is blurred in place.

RAISES	DESCRIPTION
`ValueError`	If `strength` or `feather_radius` is invalid.

Note

Processing is limited to a padded region of interest; padding includes both feather distance and Gaussian context to avoid seams at ROI edges. The non-negative strength is truncated to an integer, changed to the next odd width when even, and clamped to at least three pixels; call this width \(k\). OpenCV infers the Gaussian standard deviation from \(k\) because GaussianBlur receives sigmaX=0 (and the default zero sigmaY). For \(h=(k-1)/2\), the ROI blur is the discrete Gaussian convolution

\[ G(I)_{x,y,c} = \sum_{i=-h}^{h}\sum_{j=-h}^{h} K_\sigma(i,j)I_{x-i,y-j,c},\qquad K_\sigma(i,j)=\frac{1}{Z} \exp\!\left(-\frac{i^2+j^2}{2\sigma^2}\right), \]

where \(Z\) normalizes the finite kernel to sum to one. For distance \(d\) outside the union of box interiors and feather radius \(r\), the feather alpha is

\[ u=\operatorname{clip}\!\left(1-\frac{d}{r},0,1\right),\qquad \alpha=\operatorname{smoothstep}(u)=u^2(3-2u). \]

Box interiors have \(\alpha=1\). Each output channel is

\[ O_{x,y,c} = \operatorname{astype}_{\operatorname{dtype}(I)} \!\left(\operatorname{rint}\!\left( (1-\alpha_{x,y})I_{x,y,c}+ \alpha_{x,y}G(I)_{x,y,c}\right)\right). \]

The input frame is updated in place, and pixels with zero alpha are left unchanged.

Example

blurred = apply_masked_blur(frame, tracked_boxes, strength=15.0)

`overlay_alpha_mask(frame: np.ndarray, alpha_mask: np.ndarray, color_rgb: tuple[int, int, int] = (255, 48, 48), opacity: float = 0.32) -> np.ndarray`

Draw a semi-transparent RGB highlight for a blur alpha mask.

PARAMETER	DESCRIPTION
`frame`	RGB image to overlay. TYPE: `ndarray`
`alpha_mask`	Float alpha mask with the same height and width. TYPE: `ndarray`
`color_rgb`	Highlight color in RGB channel order. TYPE: `tuple[int, int, int]` DEFAULT: `(255, 48, 48)`
`opacity`	Maximum overlay opacity from 0 to 1. TYPE: `float` DEFAULT: `0.32`

RETURNS	DESCRIPTION
`ndarray`	A copy of `frame` with the mask highlight.

RAISES	DESCRIPTION
`ValueError`	If dimensions differ or opacity is outside `0..1`.

Note

Mask alpha modulates the maximum color opacity, so the feather remains visually gradual instead of appearing as a hard rectangle.

Example

preview = overlay_alpha_mask(frame, mask)