image

Module for differentiable image-transform primitives.

These utilities are used as building blocks for image-similarity privacy losses (see stainedglass_core.loss.image_similarity) but are kept generic so callers can compose them for other image-domain transforms.

Functions:

Name	Description
`gamma_correct`	Apply gamma correction `x ** gamma` with a floor that keeps the gradient finite at zero.
`gaussian_blur_2d`	Apply a 2D Gaussian blur via separable 1D convolutions.
`haar_dwt`	Single-level 2D Haar discrete wavelet transform.
`haar_idwt`	Inverse single-level 2D Haar DWT.
`minmax_normalize_per_image`	Min-max normalize each image in a batch into the [0, 1] range.
`rgb_to_grayscale_luma`	Convert an RGB image tensor to a single-channel luma tensor using BT.709 weights.
`sobel_magnitude`	Compute the Sobel gradient magnitude of a single-channel image.
`standardize_sigmoid`	Per-image z-score normalize each image then apply sigmoid to land in (0, 1).
`wavelet_denoise_haar`	Denoise via single-level Haar DWT soft-thresholding of detail subbands.

gamma_correct ¶

gamma_correct(
    x: Tensor, gamma: float, *, input_floor: float = 1e-06
) -> torch.Tensor

Apply gamma correction x ** gamma with a floor that keeps the gradient finite at zero.

For gamma < 1 the gradient gamma * x ** (gamma - 1) diverges as x -> 0. The input_floor clamp keeps that gradient bounded.

Parameters:

Name	Type	Description	Default
`x` ¶	`Tensor`	Non-negative tensor.	required
`gamma` ¶	`float`	Gamma exponent.	required
`input_floor` ¶	`float`	Floor applied to `x` before exponentiation.	`1e-06`

Returns:

Type	Description
`torch.Tensor`	Tensor with gamma applied elementwise.

gaussian_blur_2d ¶

gaussian_blur_2d(x: Tensor, sigma: float) -> torch.Tensor

Apply a 2D Gaussian blur via separable 1D convolutions.

The kernel size is set to 2 * ceil(3 * sigma) + 1 so the truncation error is negligible. The 1D kernel is normalized to sum to 1.

Parameters:

Name	Type	Description	Default
`x` ¶	`Tensor`	Tensor of shape `[B, C, H, W]`.	required
`sigma` ¶	`float`	Standard deviation of the Gaussian kernel in pixels. Must be positive and finite.	required

Returns:

Type	Description
`torch.Tensor`	Blurred tensor of the same shape as `x`.

Raises:

Type	Description
`ValueError`	If `sigma` is not positive or not finite.

haar_dwt ¶

haar_dwt(
    x: Tensor,
) -> tuple[
    torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor
]

Single-level 2D Haar discrete wavelet transform.

The input's last two dimensions must be even. The output contains the approximation subband LL plus three detail subbands LH, HL, HH at half resolution.

Parameters:

Name	Type	Description	Default
`x` ¶	`Tensor`	Tensor of shape `[B, C, H, W]` with `H` and `W` even.	required

Returns:

Type	Description
`tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]`	Tuple `(LL, LH, HL, HH)` each of shape `[B, C, H / 2, W / 2]`.

Raises:

Type	Description
`ValueError`	If the last two dimensions are not even.

haar_idwt ¶

haar_idwt(
    ll: Tensor, lh: Tensor, hl: Tensor, hh: Tensor
) -> torch.Tensor

Inverse single-level 2D Haar DWT.

Parameters:

Name	Type	Description	Default
`ll` ¶	`Tensor`	Approximation subband of shape `[B, C, H / 2, W / 2]`.	required
`lh` ¶	`Tensor`	Horizontal-detail subband of the same shape.	required
`hl` ¶	`Tensor`	Vertical-detail subband of the same shape.	required
`hh` ¶	`Tensor`	Diagonal-detail subband of the same shape.	required

Returns:

Type	Description
`torch.Tensor`	Reconstructed tensor of shape `[B, C, H, W]`.

minmax_normalize_per_image ¶

minmax_normalize_per_image(
    x: Tensor, *, eps: float = 0.01
) -> torch.Tensor

Min-max normalize each image in a batch into the [0, 1] range.

The per-image min and max are computed over all non-batch dimensions and are detached from the graph so gradients flow only through the per-pixel rescaling, not through the extrema. This keeps the gradient signal smooth instead of spiking on the single pixels that happen to set the min/max.

Distinct from batchwise_min_max_normalize, which does not detach the extrema and emits NaN when the per-image range is zero.

Parameters:

Name	Type	Description	Default
`x` ¶	`Tensor`	Tensor of shape `[B, ...]`.	required
`eps` ¶	`float`	Floor applied to the `(max - min)` denominator. Bounds the backward gradient at `1 / eps`.	`0.01`

Returns:

Type	Description
`torch.Tensor`	Tensor of the same shape with each image rescaled to [0, 1]. Images that are
`torch.Tensor`	constant across all pixels are rescaled using `eps` as the denominator and
`torch.Tensor`	will be close to zero.

rgb_to_grayscale_luma ¶

rgb_to_grayscale_luma(x: Tensor) -> torch.Tensor

Convert an RGB image tensor to a single-channel luma tensor using BT.709 weights.

Parameters:

Name	Type	Description	Default
`x` ¶	`Tensor`	RGB tensor of shape `[B, 3, H, W]`.	required

Returns:

Type	Description
`torch.Tensor`	Luma tensor of shape `[B, 1, H, W]` with the same dtype/device as `x`.

sobel_magnitude ¶

sobel_magnitude(
    gray: Tensor, *, eps: float = 1e-06
) -> torch.Tensor

Compute the Sobel gradient magnitude of a single-channel image.

Apply horizontal and vertical 3x3 Sobel filters and return sqrt(Gx^2 + Gy^2 + eps). The eps inside the square root keeps the gradient finite where the magnitude approaches zero.

Parameters:

Name	Type	Description	Default
`gray` ¶	`Tensor`	Single-channel image tensor of shape `[B, 1, H, W]`.	required
`eps` ¶	`float`	Epsilon added inside the sqrt to keep the backward gradient finite at zero magnitude.	`1e-06`

Returns:

Type	Description
`torch.Tensor`	Edge magnitude tensor of shape `[B, 1, H, W]`.

standardize_sigmoid ¶

standardize_sigmoid(
    x: Tensor, *, eps: float = 1e-05
) -> torch.Tensor

Per-image z-score normalize each image then apply sigmoid to land in (0, 1).

Mean and std are computed per-image over all non-batch dimensions and detached from the graph so gradients flow only through the per-pixel rescaling. Compared to min-max normalization, standardization uses the first and second moments of the entire image instead of two extremal pixels, producing a smoother gradient signal that is less dominated by outliers.

Parameters:

Name	Type	Description	Default
`x` ¶	`Tensor`	Tensor of shape `[B, ...]`.	required
`eps` ¶	`float`	Floor applied to the per-image standard deviation to keep the backward gradient finite.	`1e-05`

Returns:

Type	Description
`torch.Tensor`	Tensor of the same shape with values in (0, 1).

wavelet_denoise_haar ¶

wavelet_denoise_haar(
    x: Tensor, threshold: float
) -> torch.Tensor

Denoise via single-level Haar DWT soft-thresholding of detail subbands.

Apply the Haar DWT, soft-threshold each of the three detail subbands (LH, HL, HH) at threshold, keep the approximation subband LL unchanged, and invert the transform. This suppresses small high-frequency coefficients (typically noise) while preserving coarse structure.

Parameters:

Name	Type	Description	Default
`x` ¶	`Tensor`	Tensor of shape `[B, C, H, W]` with `H` and `W` even.	required
`threshold` ¶	`float`	Soft-threshold value applied to the detail coefficients.	required

Returns:

Type	Description
`torch.Tensor`	Denoised tensor of the same shape as `x`.

Raises:

Type	Description
`ValueError`	If the last two dimensions are not even.

image

gamma_correct ¶

`x` ¶

`gamma` ¶

`input_floor` ¶

gaussian_blur_2d ¶

`x` ¶

`sigma` ¶

haar_dwt ¶

`x` ¶

haar_idwt ¶

`ll` ¶

`lh` ¶

`hl` ¶

`hh` ¶

minmax_normalize_per_image ¶

`x` ¶

`eps` ¶

rgb_to_grayscale_luma ¶

`x` ¶

sobel_magnitude ¶

`gray` ¶

`eps` ¶

standardize_sigmoid ¶

`x` ¶

`eps` ¶

wavelet_denoise_haar ¶

`x` ¶

`threshold` ¶

image

gamma_correct ¶

x ¶

gamma ¶

input_floor ¶

gaussian_blur_2d ¶

x ¶

sigma ¶

haar_dwt ¶

x ¶

haar_idwt ¶

ll ¶

lh ¶

hl ¶

hh ¶

minmax_normalize_per_image ¶

x ¶

eps ¶

rgb_to_grayscale_luma ¶

x ¶

sobel_magnitude ¶

gray ¶

eps ¶

standardize_sigmoid ¶

x ¶

eps ¶

wavelet_denoise_haar ¶

x ¶

threshold ¶

`x` ¶

`gamma` ¶

`input_floor` ¶

`x` ¶

`sigma` ¶

`x` ¶

`ll` ¶

`lh` ¶

`hl` ¶

`hh` ¶

`x` ¶

`eps` ¶

`x` ¶

`gray` ¶

`eps` ¶

`x` ¶

`eps` ¶

`x` ¶

`threshold` ¶