Merge branch 'main' into Custom-video-data-support-openvinotoolkit#1722-&-openvinotoolkit#1721

Author: Bepitic

.ci/Dockerfile

@@ -5,7 +5,7 @@ ARG HTTP_PROXY
 ARG HTTPS_PROXY
 ARG NO_PROXY
 
-FROM nvidia/cuda:12.3.2-devel-ubuntu20.04 AS python_base_cuda
+FROM nvidia/cuda:12.4.0-devel-ubuntu20.04 AS python_base_cuda
 LABEL maintainer="Anomalib Development Team"
 
 # Setup proxies

CHANGELOG.md

@@ -10,6 +10,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Changed
 
+- 🔨Rename OptimalF1 to F1Max for consistency with the literature, by @samet-akcay in https://github.com/openvinotoolkit/anomalib/pull/1980
+- 🐞Update OptimalF1 score to use BinaryPrecisionRecallCurve and remove num_classes by @ashwinvaidya17 in https://github.com/openvinotoolkit/anomalib/pull/1972
+
 ### Deprecated
 
 ### Fixed
@@ -18,7 +21,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 **Full Changelog**:
 
-## [v1.0.1] - Unreleased
+## [v1.0.1] - 2024-03-27
 
 ### Added
 

configs/model/padim.yaml

@@ -5,7 +5,6 @@ model:
       - layer1
       - layer2
       - layer3
-    input_size: null
     backbone: resnet18
     pre_trained: true
     n_features: null

docs/source/markdown/guides/how_to/data/index.md

@@ -13,11 +13,19 @@ This section contains tutorials on how to fully utilize the data components of a
 Learn more about how to use `Folder` dataset to train anomalib models on your custom data.
 :::
 
+:::{grid-item-card} {octicon}`table` Input tiling
+:link: ./input_tiling
+:link-type: doc
+
+Learn more about how to use the tiler for input tiling.
+:::
+
 ::::
 
 ```{toctree}
 :caption: Data
 :hidden:
 
 ./custom_data
+./input_tiling
 ```

docs/source/markdown/guides/how_to/data/input_tiling.md

@@ -0,0 +1,119 @@
+# Input tiling
+
+This tutorial will show you how to tile the input to a model, using the {py:class}`Tiler <anomalib.data.utils.tiler.Tiler>`.
+
+```{warning}
+This tutorial assumes that you have already installed anomalib.
+If not, please refer to the [Installation](../../../../index.md#installation) section.
+```
+
+```{warning}
+Only selected models support tiling.
+In the current version of Anomalib, these are:
+
+- [Padim](../../reference/models/image/padim.md)
+- [Patchcore](../../reference/models/image/patchcore.md)
+- [Reverse Distillation](../../reference/models/image/reverse_distillation.md)
+- [STFPM](../../reference/models/image/stfpm.md)
+
+```
+
+## General tiling information
+
+The general idea of input tiling is that the image is split into a rectangular grid of tiles as a pre-processing step, usually in order to reduce memory usage.
+By passing individual tiles to the model as input instead of full images, tiling reduces the model's input dimensions, while maintaining the effective input resolution of the images content-wise.
+
+```{note}
+Tiler in Anomalib by default stacks the tiles batch-wise, so the memory consumption stays unchanged if the batch size is not reduced.
+```
+
+The process of tiling is parametrized by four parameters `tile_size`, `stride`, `remove_border_count`, and `mode`.
+
+- `tile_size` - determines the size of our tiles. Can be either a single number (square tiles) or a tuple.
+- `stride` - determines by how much we move in each direction when "cutting" the image into tiles. Can be either a single number (same step in both directions) or a tuple.
+- `remove_border_count` - how many pixels are removed at the border of the image before tiling (defaults to 0).
+- `mode` - what type of upscaling is used when the image isn't exactly divisible into tile-set specified by the parameters `tile_size` and `stride` (defaults to padding).
+
+In most cases, we are only interested in the first two parameters - `tile_size` and `stride`. For the other two, refer to [Tiler implementation](../../reference/data/utils/tiling.md).
+
+## Tiling setup
+
+We can utilize the tiling in two ways. Either with the CLI or by using the API.
+In both cases, we need to use the {py:class}`TilerConfigurationCallback <anomalib.callbacks.TilerConfigurationCallback>`.
+This callback is responsible for assigning the tiler object to the model before the training starts.
+
+```{note}
+Besides the arguments from {py:class}`Tiler <anomalib.data.utils.tiler.Tiler>`, {py:class}`TilerConfigurationCallback <anomalib.callbacks.TilerConfigurationCallback>` also has an additional `enable` argument, which must be set to `True` if we want the tiling to happen.
+```
+
+::::{tab-set}
+
+:::{tab-item} API
+
+To use tiling from the API, we need to initialize the {py:class}`TilerConfigurationCallback <anomalib.callbacks.TilerConfigurationCallback>` and pass it to the engine:
+
+```{code-block} python
+:lineno-start: 1
+:emphasize-lines: 12, 15
+# Import the required modules
+from anomalib.data import MVTec
+from anomalib.engine import Engine
+from anomalib.models import Padim
+from anomalib.callbacks import TilerConfigurationCallback
+
+# Initialize the datamodule and model
+datamodule = MVTec(num_workers=0, image_size=(128, 128))
+model = Padim()
+
+# prepare tiling configuration callback
+tiler_config_callback = TilerConfigurationCallback(enable=True, tile_size=[128, 64], stride=64)
+
+# pass the tiling configuration callback to the engine
+engine = Engine(image_metrics=["AUROC"], pixel_metrics=["AUROC"], callbacks=[tiler_config_callback])
+
+# train the model (tiling is seamlessly utilized in the background)
+engine.fit(datamodule=datamodule, model=model)
+```
+
+:::
+
+:::{tab-item} CLI
+
+### Using CLI arguments
+
+We can set the {py:class}`TilerConfigurationCallback <anomalib.callbacks.TilerConfigurationCallback>` and its init arguments directly from the CLI.
+
+We pass it as trainer.callback, and then provide the parameters:
+
+```{code-block} bash
+:emphasize-lines: 2, 3, 4, 5
+anomalib train --model Padim --data anomalib.data.MVTec
+    --trainer.callbacks anomalib.callbacks.tiler_configuration.TilerConfigurationCallback
+    --trainer.callbacks.enable True
+    --trainer.callbacks.tile_size 128
+    --trainer.callbacks.stride 64
+```
+
+### Using config
+
+For more advanced configuration, we can prepare the config file:
+
+```{code-block} yaml
+:lineno-start: 1
+trainer.callbacks:
+  class_path: anomalib.callbacks.tiler_configuration.TilerConfigurationCallback
+  init_args:
+    enable: True
+    tile_size: [128, 256]
+    stride: 64
+```
+
+Then use the config from the CLI:
+
+```{code-block} bash
+anomalib train --model Padim --data anomalib.data.MVTec --config config.yaml
+```
+
+:::
+
+::::

docs/source/markdown/guides/reference/callbacks/index.md

@@ -3,6 +3,6 @@
 ```{eval-rst}
 .. automodule:: anomalib.callbacks
    :members:
-   :exclude-members: get_visualization_callbacks, TilerConfigurationCallback
+   :exclude-members: get_visualization_callbacks
    :show-inheritance:
 ```

src/anomalib/data/utils/tiler.py

@@ -378,7 +378,7 @@ def tile(self, image: torch.Tensor, use_random_tiling: bool = False) -> torch.Te
         if self.input_h < self.tile_size_h or self.input_w < self.tile_size_w:
             msg = (
                 f"One of the edges of the tile size {self.tile_size_h, self.tile_size_w} is larger than "
-                f"that of the image {{self.input_h, self.input_w}}."
+                f"that of the image {self.input_h, self.input_w}."
             )
             raise ValueError(
                 msg,

src/anomalib/metrics/__init__.py

@@ -3,7 +3,6 @@
 # Copyright (C) 2022-2024 Intel Corporation
 # SPDX-License-Identifier: Apache-2.0
 
-
 import importlib
 import logging
 from collections.abc import Callable
@@ -17,6 +16,7 @@
 from .aupro import AUPRO
 from .auroc import AUROC
 from .collection import AnomalibMetricCollection
+from .f1_max import F1Max
 from .f1_score import F1Score
 from .min_max import MinMax
 from .precision_recall_curve import BinaryPrecisionRecallCurve
@@ -30,6 +30,7 @@
     "AnomalyScoreDistribution",
     "BinaryPrecisionRecallCurve",
     "F1AdaptiveThreshold",
+    "F1Max",
     "F1Score",
     "ManualThreshold",
     "MinMax",

src/anomalib/metrics/aupr.py

@@ -6,14 +6,14 @@
 
 import torch
 from matplotlib.figure import Figure
-from torchmetrics import PrecisionRecallCurve
+from torchmetrics.classification import BinaryPrecisionRecallCurve
 from torchmetrics.utilities.compute import auc
 from torchmetrics.utilities.data import dim_zero_cat
 
 from .plotting_utils import plot_figure
 
 
-class AUPR(PrecisionRecallCurve):
+class AUPR(BinaryPrecisionRecallCurve):
     """Area under the PR curve.
 
     This metric computes the area under the precision-recall curve.

src/anomalib/metrics/f1_max.py

@@ -0,0 +1,100 @@
+"""Implementation of F1Max score based on TorchMetrics."""
+
+# Copyright (C) 2022-2024 Intel Corporation
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+
+import torch
+from torchmetrics import Metric
+
+from anomalib.metrics.precision_recall_curve import BinaryPrecisionRecallCurve
+
+logger = logging.getLogger(__name__)
+
+
+class F1Max(Metric):
+    """F1Max Metric for Computing the Maximum F1 Score.
+
+    This class is designed to calculate the maximum F1 score from the precision-
+    recall curve for binary classification tasks. The F1 score is a harmonic
+    mean of precision and recall, offering a balance between these two metrics.
+    The maximum F1 score (F1-Max) is particularly useful in scenarios where an
+    optimal balance between precision and recall is desired, such as in
+    imbalanced datasets or when both false positives and false negatives carry
+    significant costs.
+
+    After computing the F1Max score, the class also identifies and stores the
+    threshold that yields this maximum F1 score, which providing insight into
+    the optimal point for the classification decision.
+
+    Args:
+        **kwargs: Variable keyword arguments that can be passed to the parent class.
+
+    Attributes:
+        full_state_update (bool): Indicates whether the metric requires updating
+            the entire state. Set to False for this metric as it calculates the
+            F1 score based on the current state without needing historical data.
+        precision_recall_curve (BinaryPrecisionRecallCurve): Utility to compute
+            precision and recall values across different thresholds.
+        threshold (torch.Tensor): Stores the threshold value that results in the
+            maximum F1 score.
+
+    Examples:
+        >>> from anomalib.metrics import F1Max
+        >>> import torch
+
+        >>> preds = torch.tensor([0.1, 0.4, 0.35, 0.8])
+        >>> target = torch.tensor([0, 0, 1, 1])
+
+        >>> f1_max = F1Max()
+        >>> f1_max.update(preds, target)
+
+        >>> optimal_f1_score = f1_max.compute()
+        >>> print(f"Optimal F1 Score: {f1_max_score}")
+        >>> print(f"Optimal Threshold: {f1_max.threshold}")
+
+    Note:
+        - Use `update` method to input predictions and target labels.
+        - Use `compute` method to calculate the maximum F1 score after all
+          updates.
+        - Use `reset` method to clear the current state and prepare for a new
+          set of calculations.
+    """
+
+    full_state_update: bool = False
+
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+
+        self.precision_recall_curve = BinaryPrecisionRecallCurve()
+
+        self.threshold: torch.Tensor
+
+    def update(self, preds: torch.Tensor, target: torch.Tensor, *args, **kwargs) -> None:
+        """Update the precision-recall curve metric."""
+        del args, kwargs  # These variables are not used.
+
+        self.precision_recall_curve.update(preds, target)
+
+    def compute(self) -> torch.Tensor:
+        """Compute the value of the optimal F1 score.
+
+        Compute the F1 scores while varying the threshold. Store the optimal
+        threshold as attribute and return the maximum value of the F1 score.
+
+        Returns:
+            Value of the F1 score at the optimal threshold.
+        """
+        precision: torch.Tensor
+        recall: torch.Tensor
+        thresholds: torch.Tensor
+
+        precision, recall, thresholds = self.precision_recall_curve.compute()
+        f1_score = (2 * precision * recall) / (precision + recall + 1e-10)
+        self.threshold = thresholds[torch.argmax(f1_score)]
+        return torch.max(f1_score)
+
+    def reset(self) -> None:
+        """Reset the metric."""
+        self.precision_recall_curve.reset()