SuperADD#

Implementation of the SuperADD model for anomaly detection and segmentation.

Architecture#

SuperADD Architecture

SuperADD extracts multi-layer Vision Transformer token features from a pretrained DINOv3 backbone over overlapping image patches, builds a per-layer memory bank from normal training images using distance-based coreset subsampling, and detects anomalies by nearest-neighbor search against this memory bank.

Usage#

CLI training with default configuration:

anomalib train --model SuperADD --data MVTecAD2 --data.category bottle

Python API:

from anomalib.data import MVTecAD2
from anomalib.engine import Engine
from anomalib.models import SuperADD

datamodule = MVTecAD2()
model = SuperADD()
engine = Engine()

engine.fit(datamodule=datamodule, model=model)

API Reference#

SuperADD: PatchCore-style anomaly detection on a DINOv3 backbone.

SuperADD is an anomaly detection model that builds a memory bank of patch features extracted from a pretrained DINOv3 Vision Transformer. Multi-layer ViT token features are computed over overlapping image patches, a per-layer memory bank is built from normal training images via distance-based coreset subsampling, and test images are scored by nearest-neighbor distance to the bank.

Example

>>> from anomalib.data import MVTecAD2
>>> from anomalib.models import SuperADD
>>> from anomalib.engine import Engine
>>> # Initialize model and data
>>> datamodule = MVTecAD2()
>>> model = SuperADD()
>>> # Train using the Engine
>>> engine = Engine()
>>> engine.fit(model=model, datamodule=datamodule)
>>> # Get predictions
>>> predictions = engine.predict(model=model, datamodule=datamodule)
class anomalib.models.image.super_add.SuperADD(backbone='vit_huge_plus_patch16_dinov3', patch_size=448, patch_overlap=16, layers=None, gaussian_blur_sigma=4.0, score_quantile=0.001, precision=PrecisionType.FLOAT32, pre_processor=True, post_processor=True, evaluator=True, visualizer=True)#

Bases: MemoryBankMixin, AnomalibModule

SuperADD Lightning Module for anomaly detection.

This class implements the SuperADD algorithm, which uses a memory bank of patch features for anomaly detection. Multi-layer token features are extracted from a pretrained DINOv3 Vision Transformer over overlapping image patches and stored in a per-layer memory bank. Anomalies are detected by comparing test image patches against the stored features using nearest neighbor search.

The model works in two phases: 1. Training: Extract and store patch features from normal training images,

then build a coreset memory bank.

  1. Inference: Compare test image patches against the stored features to detect anomalies.

Parameters:
  • backbone (str) – Name of the timm DINOv3 backbone used for feature extraction. Defaults to "vit_huge_plus_patch16_dinov3".

  • patch_size (int) – Side length (in pixels) of the overlapping patches the input image is split into before being passed to the backbone. Defaults to 448.

  • patch_overlap (int) – Overlap (in pixels) between neighboring patches. Defaults to 16.

  • layers (list[int] | None) – List of encoder layer indices to extract features from. If None, DINO_TARGET_LAYERS of the respective model size.

  • gaussian_blur_sigma (float) – Standard deviation of the Gaussian filter applied to the anomaly map before scoring. Set to 0 to disable. Defaults to 4.0.

  • score_quantile (float) – Fraction of the highest anomaly map pixels averaged into the image-level score. Defaults to 1e-3.

  • precision (str | PrecisionType) – Precision type for model computations. Can be either a string ("float32", "float16") or a PrecisionType enum value. Defaults to PrecisionType.FLOAT32.

  • pre_processor (Module | bool) – Pre-processor instance or bool flag. Defaults to True.

  • post_processor (Module | bool) – Post-processor instance or bool flag. Defaults to True.

  • evaluator (Evaluator | bool) – Evaluator instance or bool flag. Defaults to True.

  • visualizer (Visualizer | bool) – Visualizer instance or bool flag. Defaults to True.

Raises:

ValueError – If an unsupported precision value is provided.

Example

>>> from anomalib.data import MVTecAD2
>>> from anomalib.models import SuperADD
>>> from anomalib.engine import Engine
>>> datamodule = MVTecAD2()
>>> model = SuperADD()
>>> engine = Engine()
>>> engine.fit(model=model, datamodule=datamodule)
>>> predictions = engine.predict(model=model, datamodule=datamodule)

See also

  • anomalib.models.image.super_add.torch_model.SuperADDModel:

    PyTorch implementation of the SuperADD model

  • anomalib.models.components.AnomalibModule:

    Base class for all anomaly detection models

  • anomalib.models.components.MemoryBankMixin:

    Mixin class for models using feature memory banks

static configure_optimizers()#

Configure optimizers.

Returns:

SuperADD requires no optimization.

Return type:

None

static configure_post_processor()#

Configure the default post-processor.

SuperADD uses a percentile-based threshold calibrated on the anomaly scores of normal validation images (95th percentile scaled by 1.421, following the original implementation), instead of the F1-adaptive threshold. The adaptive threshold requires anomalous validation samples and otherwise degenerates to the maximum validation score, which grows with the input resolution and collapses F1 for multi-patch configurations.

Returns:

Percentile-based post-processor for SuperADD.

Return type:

PostProcessor

classmethod configure_pre_processor(image_size=None, center_crop_size=None)#

Configure the default pre-processor for SuperADD.

If valid center_crop_size is provided, the pre-processor will also perform center cropping, according to the paper.

Parameters:
  • image_size (tuple[int, int] | None) – Target size for resizing. Defaults to (448, 448).

  • center_crop_size (tuple[int, int] | None) – Size for center cropping. Defaults to None.

Returns:

Configured pre-processor instance.

Return type:

PreProcessor

Raises:

ValueError – If at least one dimension of center_crop_size is larger than correspondent image_size dimension.

Example

>>> pre_processor = SuperADD.configure_pre_processor(
...     image_size=(256, 256)
... )
>>> transformed_image = pre_processor(image)
fit()#

Apply subsampling to the embedding collected from the training set.

This method: 1. Applies coreset subsampling to reduce memory requirements

Return type:

None

property learning_type: LearningType#

Get the learning type.

Returns:

Always LearningType.ONE_CLASS as SuperADD only

trains on normal samples

Return type:

LearningType

property trainer_arguments: dict[str, Any]#

Get default trainer arguments for SuperADD.

Returns:

Trainer arguments
  • gradient_clip_val: 0 (no gradient clipping needed)

  • max_epochs: 1 (single pass through training data)

  • num_sanity_val_steps: 0 (skip validation sanity checks)

  • devices: 1 (only single gpu supported)

Return type:

dict[str, Any]

training_step(batch, *args, **kwargs)#

Generate feature embedding of the batch.

Parameters:
  • batch (Batch) – Input batch containing image and metadata

  • *args – Additional arguments (unused)

  • **kwargs – Additional keyword arguments (unused)

Returns:

Dummy loss tensor for Lightning compatibility

Return type:

Tensor

Note

The method stores embeddings in self.embeddings for later use in fit().

validation_step(batch, *args, **kwargs)#

Generate predictions for a batch of images.

Parameters:
  • batch (Batch) – Input batch containing images and metadata

  • *args – Additional arguments (unused)

  • **kwargs – Additional keyword arguments (unused)

Returns:

Batch with added predictions

Return type:

Union[Tensor, Mapping[str, Any], None]

Note

Predictions include anomaly maps and scores computed using nearest neighbor search.

class anomalib.models.image.super_add.SuperADDPostProcessor(pixel_threshold_percentile=95.0, pixel_threshold_factor=1.421, image_threshold_percentile=95.0, image_threshold_factor=1.0, samples_per_batch=100000, **kwargs)#

Bases: PostProcessor

Post-processor with percentile-based thresholds from normal validation data.

Instead of the F1-adaptive threshold (which requires anomalous validation samples), thresholds are set to a percentile of the validation scores of normal images, scaled by a factor, following the original SuperADD implementation.

Parameters:
  • pixel_threshold_percentile (float) – Percentile of validation anomaly map pixel scores used as the base pixel threshold. Defaults to 95.0 (original implementation value).

  • pixel_threshold_factor (float) – Multiplicative factor applied to the pixel percentile. Defaults to 1.421 (original implementation value).

  • image_threshold_percentile (float) – Percentile of validation image scores used as the base image threshold. Defaults to 95.0.

  • image_threshold_factor (float) – Multiplicative factor applied to the image percentile. Defaults to 1.0.

  • samples_per_batch (int) – Maximum number of anomaly map pixels sampled per validation batch for the percentile estimate. Defaults to 100000.

  • **kwargs – Passed to PostProcessor.

Example

>>> from anomalib.models.image.super_add import SuperADDPostProcessor
>>> post_processor = SuperADDPostProcessor(pixel_threshold_factor=1.2)
on_validation_batch_end(trainer, pl_module, outputs, *args, **kwargs)#

Collect normalization statistics and score samples for the percentile thresholds.

Unlike the base class, the F1-adaptive threshold metrics are not updated; the thresholds are derived from the collected score samples in on_validation_epoch_end() instead.

Return type:

None

on_validation_epoch_end(trainer, pl_module)#

Compute the percentile-based thresholds and the normalization statistics.

Return type:

None