run_patchcore.py

Overview

The run_patchcore.py script is the primary CLI tool for training PatchCore models on industrial anomaly detection datasets. It uses a command-chaining architecture where you specify a main command followed by three required subcommands: patch_core, sampler, and dataset.

Command Structure

python bin/run_patchcore.py [MAIN_OPTIONS] RESULTS_PATH \
  patch_core [PATCHCORE_OPTIONS] \
  sampler [SAMPLER_OPTIONS] SAMPLER_NAME \
  dataset [DATASET_OPTIONS] DATASET_NAME DATA_PATH

Main Command

Arguments

string

required

Path where training results, models, and evaluation metrics will be saved

Options

int

default:"0"

GPU device ID(s) to use for training. Can specify multiple GPUs by repeating the flag.

--gpu 0 --gpu 1  # Use GPUs 0 and 1

int

default:"0"

Random seed for reproducibility across training runs

string

default:"group"

Logging group name for organizing experiment results

string

default:"project"

Logging project name for organizing experiment results

flag

Save visualization images showing anomaly segmentation results. Useful for qualitative analysis.

flag

Save trained PatchCore model to disk for later evaluation or deployment

Subcommand: patch_core

Configures the PatchCore model architecture and training parameters.

Backbone Options

string

Short flag: -bPretrained backbone network(s) to extract features. Supports multiple backbones for ensemble models.Supported backbones:

wideresnet50 - Wide ResNet-50
wideresnet101 - Wide ResNet-101
resnext101 - ResNeXt-101
densenet201 - DenseNet-201

-b wideresnet50  # Single backbone
-b wideresnet101 -b resnext101 -b densenet201  # Ensemble

string

Short flag: -leLayer names from which to extract feature embeddings. For ensemble models with multiple backbones, prefix with backbone index (e.g., 0.layer2, 1.layer2).

# Single backbone
-le layer2 -le layer3

# Ensemble (3 backbones)
-le 0.layer2 -le 0.layer3 \
-le 1.layer2 -le 1.layer3 \
-le 2.features.denseblock2 -le 2.features.denseblock3

Embedding Dimensions

int

default:"1024"

Dimensionality of pretrained backbone features before projection

int

default:"1024"

Target dimensionality after projection. Lower values reduce memory usage.

Processing Options

choice

default:"mean"

Feature preprocessing methodChoices: mean, conv

choice

default:"mean"

Feature aggregation methodChoices: mean, mlp

Patch Parameters

int

default:"3"

Size of the neighborhood patch for anomaly scoring. Larger values provide more spatial context.

Detection tasks: typically 3
Segmentation tasks: typically 5

string

default:"max"

Method for computing patch-level anomaly scores

float

default:"0.0"

Overlap ratio between adjacent patches (0.0 = no overlap, 0.5 = 50% overlap)

int

Short flag: -paAdditional patch sizes for multi-scale aggregation

Anomaly Scoring

int

default:"5"

Number of nearest neighbors (k-NN) used for anomaly scoring

Detection: typically 1
Segmentation: typically 3 or 5

FAISS Options

flag

Use GPU-accelerated FAISS for nearest neighbor search. Significantly speeds up inference.

int

default:"8"

Number of CPU workers for FAISS operations

Subcommand: sampler

Configures coreset sampling strategy for reducing memory bank size.

Arguments

string

required

Sampler type to useOptions:

identity - Use all training features (no sampling)
greedy_coreset - Greedy coreset selection
approx_greedy_coreset - Approximate greedy coreset (faster)

Options

float

default:"0.1"

Short flag: -pPercentage of training features to retain in the memory bank

0.1 = 10% (faster, less memory)
0.01 = 1% (even faster, minimal accuracy loss)

Subcommand: dataset

Configures dataset loading and preprocessing.

Arguments

string

required

Dataset type. Currently supported: mvtec

path

required

Path to the dataset root directory. Must exist.

Options

string

required

Short flag: -dDataset categories to train on. For MVTec AD, this includes:bottle, cable, capsule, carpet, grid, hazelnut, leather, metal_nut, pill, screw, tile, toothbrush, transistor, wood, zipper

-d bottle -d cable -d capsule  # Train on specific categories

float

default:"1.0"

Fraction of training data to use for training (remainder used for validation)

1.0 = use all training data
0.8 = 80% train, 20% validation

int

default:"2"

Batch size for data loading

int

default:"8"

Number of worker processes for data loading

int

default:"256"

Image resize dimension (before center cropping)

int

default:"224"

Final image size after center cropping

224 - Standard ImageNet size
320 - Higher resolution for better segmentation

flag

Apply data augmentation during training

Examples

Basic Training (Single Dataset)

python bin/run_patchcore.py \
  --gpu 0 \
  --seed 0 \
  --save_patchcore_model \
  results/my_experiment \
  patch_core \
    -b wideresnet50 \
    -le layer2 -le layer3 \
    --faiss_on_gpu \
    --pretrain_embed_dimension 1024 \
    --target_embed_dimension 1024 \
    --anomaly_scorer_num_nn 1 \
    --patchsize 3 \
  sampler -p 0.1 approx_greedy_coreset \
  dataset \
    --resize 256 \
    --imagesize 224 \
    -d bottle \
    mvtec /path/to/mvtec

Baseline Detection Model (IM224)

Wide ResNet-50, 10% coreset, optimized for detection:

python bin/run_patchcore.py \
  --gpu 0 \
  --seed 0 \
  --save_patchcore_model \
  --log_group IM224_WR50_L2-3_P01_D1024-1024_PS-3_AN-1_S0 \
  --log_project MVTecAD_Results \
  results \
  patch_core \
    -b wideresnet50 \
    -le layer2 -le layer3 \
    --faiss_on_gpu \
    --pretrain_embed_dimension 1024 \
    --target_embed_dimension 1024 \
    --anomaly_scorer_num_nn 1 \
    --patchsize 3 \
  sampler -p 0.1 approx_greedy_coreset \
  dataset \
    --resize 256 \
    --imagesize 224 \
    -d bottle -d cable -d capsule \
    mvtec /path/to/mvtec

Expected Performance: Instance AUROC: 0.992, Pixelwise AUROC: 0.981

Ensemble Model (IM224)

Multiple backbones for improved accuracy:

python bin/run_patchcore.py \
  --gpu 0 \
  --seed 3 \
  --save_patchcore_model \
  --log_group IM224_Ensemble_L2-3_P001_D1024-384_PS-3_AN-1_S3 \
  results \
  patch_core \
    -b wideresnet101 -b resnext101 -b densenet201 \
    -le 0.layer2 -le 0.layer3 \
    -le 1.layer2 -le 1.layer3 \
    -le 2.features.denseblock2 -le 2.features.denseblock3 \
    --faiss_on_gpu \
    --pretrain_embed_dimension 1024 \
    --target_embed_dimension 384 \
    --anomaly_scorer_num_nn 1 \
    --patchsize 3 \
  sampler -p 0.01 approx_greedy_coreset \
  dataset \
    --resize 256 \
    --imagesize 224 \
    -d bottle -d cable -d capsule \
    mvtec /path/to/mvtec

Expected Performance: Instance AUROC: 0.993, Pixelwise AUROC: 0.981

High-Resolution Segmentation (IM320)

Optimized for pixel-level anomaly segmentation:

python bin/run_patchcore.py \
  --gpu 0 \
  --seed 22 \
  --save_patchcore_model \
  --save_segmentation_images \
  results \
  patch_core \
    -b wideresnet50 \
    -le layer2 -le layer3 \
    --faiss_on_gpu \
    --pretrain_embed_dimension 1024 \
    --target_embed_dimension 1024 \
    --anomaly_scorer_num_nn 3 \
    --patchsize 5 \
  sampler -p 0.01 approx_greedy_coreset \
  dataset \
    --resize 366 \
    --imagesize 320 \
    -d bottle \
    mvtec /path/to/mvtec

Expected Performance: Instance AUROC: 0.99, Pixelwise AUROC: 0.984

Output Files

The script creates the following directory structure:

results/
└── [log_project]/
    └── [log_group]/
        ├── models/
        │   └── mvtec_[category]/
        │       ├── *.faiss           # Nearest neighbor index
        │       └── *.pkl             # Model parameters
        ├── segmentation_images/      # (if --save_segmentation_images)
        │   └── mvtec_[category]/
        └── results.csv               # Evaluation metrics

Metrics Computed

The script automatically computes:

Instance AUROC: Image-level anomaly detection accuracy
Full Pixel AUROC: Pixel-level segmentation accuracy (all images)
Anomaly Pixel AUROC: Pixel-level segmentation accuracy (anomalous images only)

All metrics are saved to results.csv with mean scores across all datasets.

Tips

For faster training: Use --faiss_on_gpu and lower coreset percentage (-p 0.01)

For better segmentation: Increase --imagesize to 320, --patchsize to 5, and --anomaly_scorer_num_nn to 3-5

For ensemble models: Use different backbones and prefix layer names with backbone index (e.g., 0.layer2, 1.layer2)

Core Components

Utilities

CLI Tools

Overview

Command Structure

Main Command

Arguments

Options

Subcommand: patch_core

Backbone Options

Embedding Dimensions

Processing Options

Patch Parameters

Anomaly Scoring

FAISS Options

Subcommand: sampler

Arguments

Options

Subcommand: dataset

Arguments

Options

Examples

Basic Training (Single Dataset)

Baseline Detection Model (IM224)

Ensemble Model (IM224)

High-Resolution Segmentation (IM320)

Output Files

Metrics Computed

Tips

​Overview

​Command Structure

​Main Command

​Arguments

​Options

​Subcommand: patch_core

​Backbone Options

​Embedding Dimensions

​Processing Options

​Patch Parameters

​Anomaly Scoring

​FAISS Options

​Subcommand: sampler

​Arguments

​Options

​Subcommand: dataset

​Arguments

​Options

​Examples

​Basic Training (Single Dataset)

​Baseline Detection Model (IM224)

​Ensemble Model (IM224)

​High-Resolution Segmentation (IM320)

​Output Files

​Metrics Computed

​Tips

Overview

Command Structure

Main Command

Arguments

Options

Subcommand: patch_core

Backbone Options

Embedding Dimensions

Processing Options

Patch Parameters

Anomaly Scoring

FAISS Options

Subcommand: sampler

Arguments

Options

Subcommand: dataset

Arguments

Options

Examples

Basic Training (Single Dataset)

Baseline Detection Model (IM224)

Ensemble Model (IM224)

High-Resolution Segmentation (IM320)

Output Files

Metrics Computed

Tips