cloak

Module for cloak loss functions.

Functions:

Name	Description
composite_cloak_loss_factory	Create a loss function to train a Stained Glass Transform using negative_log_mean.
image_similarity_cloak_loss_factory	Create a loss function combining a task loss with the image-similarity privacy loss.

composite_cloak_loss_factory

composite_cloak_loss_factory(
    noisy_model: NoisyModel[ModuleT, ..., NoiseLayerT],
    loss_function: Callable[LossFunctionP, Tensor],
    alpha: float,
    respect_std_mask: bool = True,
) -> tuple[
    Callable[sg_transform_loss.LossFunctionP, torch.Tensor],
    Callable[[], ComponentLossesDict],
    Callable[[], HyperparametersDict],
]

Create a loss function to train a Stained Glass Transform using negative_log_mean.

Parameters:

Name	Type	Description	Default
noisy_model	NoisyModel[ModuleT, ..., NoiseLayerT]	The model containing both the base model and the Stained Glass Transform.	required
loss_function	Callable[LossFunctionP, Tensor]	The base model task loss function to wrap.	required
alpha	float	The interpolation factor between the task loss (maximizing task performance) and the Stained Glass Transform loss (maximizing transformation strength). Should be in the range [0, 1], where 0 corresponds to higher task performance and 1 corresponds to higher transformation strength.	required
respect_std_mask	bool	Some NoiseLayers' std_estimator returns a mask tensor which determines which elements of the inputs are masked out as part of the transformation. If True, the loss function will respect this mask when computing the noise loss (i.e. only unmasked elements will contribute to the noise loss). If False, the loss function will ignore the mask and compute the noise loss over all elements. This parameter is ignored if the NoiseLayer does not provide a mask. For historical reasons, for NoiseLayers inherited from PatchCloakNoiseLayer, this parameter is ignored and the mask is never respected.	True

Returns:

Type	Description
tuple[Callable[sg_transform_loss.LossFunctionP, torch.Tensor], Callable[[], ComponentLossesDict], Callable[[], HyperparametersDict]]	A tuple of 3 functions: the composite loss function, a function to retrieve the loss components, and a function to retrieve the
tuple[Callable[sg_transform_loss.LossFunctionP, torch.Tensor], Callable[[], ComponentLossesDict], Callable[[], HyperparametersDict]]	hyperparameters. These functions may be called at most once each after a forward pass through both models.

image_similarity_cloak_loss_factory

image_similarity_cloak_loss_factory(
    noisy_model: NoisyModel[ModuleT, ..., NoiseLayerT],
    loss_function: Callable[LossFunctionP, Tensor],
    *,
    ms_ssim_weight: float,
    pearson_weight: float,
    image_mean: Sequence[float],
    image_std: Sequence[float],
    super_batched: bool = False,
    gamma_values: Sequence[float] = (0.5, 2.0),
    blur_sigma: float = 2.0,
    wavelet_threshold: float = 0.1
) -> tuple[
    Callable[sg_transform_loss.LossFunctionP, torch.Tensor],
    Callable[[], ComponentLossesDict],
    Callable[[], HyperparametersDict],
]

Create a loss function combining a task loss with the image-similarity privacy loss.

Registers two activation hooks on noisy_model.noise_layer to capture both its first positional input (the clean image) and its forward output (the noisy image), then composes multi_attacker_privacy_loss with the supplied task loss as task_loss + ms_ssim_weight * ms_ssim_total + pearson_weight * pearson_total.

Inputs to the noise layer are assumed to be channel-normalized (e.g. ImageNet normalization) — supply image_mean and image_std so the captured tensors can be denormalized into [0, 1] before MS-SSIM. Privacy: the captured tensors are only used to compute the loss; callers should not log them.

Parameters:

Name	Type	Description	Default
noisy_model	NoisyModel[ModuleT, ..., NoiseLayerT]	The model containing both the base model and the Stained Glass Transform.	required
loss_function	Callable[LossFunctionP, Tensor]	The base model task loss function to wrap. Must return a scalar tensor.	required
ms_ssim_weight	float	Weight on the aggregate MS-SSIM privacy term (mean of nine MS-SSIM components).	required
pearson_weight	float	Weight on the aggregate squared-Pearson privacy term (mean of six components).	required
image_mean	Sequence[float]	Per-channel mean used to denormalize the captured images into [0, 1].	required
image_std	Sequence[float]	Per-channel std used to denormalize the captured images into [0, 1]. Same length as image_mean.	required
super_batched	bool	Set to True when the noise layer is invoked under distillation_context(); the wrapper then slices the relevant halves of the captured input/output before computing the loss. Defaults to False for callers that supply a single [B, ...] input directly to the noise layer.	False
gamma_values	Sequence[float]	Forwarded to multi_attacker_privacy_loss.	(0.5, 2.0)
blur_sigma	float	Forwarded to multi_attacker_privacy_loss.	2.0
wavelet_threshold	float	Forwarded to multi_attacker_privacy_loss.	0.1

Returns:

Type	Description
tuple[Callable[sg_transform_loss.LossFunctionP, torch.Tensor], Callable[[], ComponentLossesDict], Callable[[], HyperparametersDict]]	A tuple of 3 functions: the composite loss function, a function to retrieve the loss components
tuple[Callable[sg_transform_loss.LossFunctionP, torch.Tensor], Callable[[], ComponentLossesDict], Callable[[], HyperparametersDict]]	(including each of the 15 named components plus the two totals and the composite loss), and a
tuple[Callable[sg_transform_loss.LossFunctionP, torch.Tensor], Callable[[], ComponentLossesDict], Callable[[], HyperparametersDict]]	function to retrieve the hyperparameters. These functions may be called at most once each after
tuple[Callable[sg_transform_loss.LossFunctionP, torch.Tensor], Callable[[], ComponentLossesDict], Callable[[], HyperparametersDict]]	a forward pass through both models.

Raises:

Type	Description
ValueError	If image_mean and image_std have different lengths.

Added in version v3.39.0. Cloak loss factory wrapping the image-similarity privacy loss.