From 295cf1b01ef0c201b322ac8754baeb8d437f1324 Mon Sep 17 00:00:00 2001 From: oynal Date: Tue, 17 Nov 2026 12:18:42 +0800 Subject: [PATCH 1/5] Factor LPIPS into MONAI perceptual loss Preserve LPIPS v0.1 distances and checkpoint keys while bundling the small calibration weights with upstream attribution. Keep the existing lpips extra as a Torchvision alias. Assisted-by: Codex Signed-off-by: oynal --- .gitignore | 1 + MANIFEST.in | 1 + docs/source/installation.md | 8 +- monai/losses/_perceptual.py | 140 ++++++++++++++++++++++++++ monai/losses/perceptual.py | 10 +- monai/losses/weights/LICENSE.LPIPS | 23 +++++ monai/losses/weights/README.md | 16 +++ monai/losses/weights/alex.pth | Bin 0 -> 6009 bytes monai/losses/weights/squeeze.pth | Bin 0 -> 10811 bytes monai/losses/weights/vgg.pth | Bin 0 -> 7289 bytes pyproject.toml | 5 +- setup.py | 2 +- tests/losses/test_perceptual_lpips.py | 80 +++++++++++++++ tests/min_tests.py | 1 + 14 files changed, 277 insertions(+), 10 deletions(-) create mode 100644 monai/losses/_perceptual.py create mode 100644 monai/losses/weights/LICENSE.LPIPS create mode 100644 monai/losses/weights/README.md create mode 100644 monai/losses/weights/alex.pth create mode 100644 monai/losses/weights/squeeze.pth create mode 100644 monai/losses/weights/vgg.pth create mode 100644 tests/losses/test_perceptual_lpips.py diff --git a/.gitignore b/.gitignore index d0bdc54018d..f74156e3968 100644 --- a/.gitignore +++ b/.gitignore @@ -168,5 +168,6 @@ runs *.gz *.pth +!monai/losses/weights/*.pth *zarr/* diff --git a/MANIFEST.in b/MANIFEST.in index d77d3b5e50a..7d931f3b060 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,2 +1,3 @@ recursive-include monai/csrc *.cpp *.cu *.h *.cuh +recursive-include monai/losses/weights *.pth LICENSE.LPIPS README.md prune tests diff --git a/docs/source/installation.md b/docs/source/installation.md index 31c99a794c1..40d9621a9c3 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -80,7 +80,13 @@ MONAI supports the extras syntax such as `pip install 'monai[nibabel]'`. The opt clearml, cucim, cupy, einops, fire, gdown, h5py, huggingface_hub, hyena, ignite, imagecodecs, itk, jsonschema, lmdb, lpips, matplotlib, metrics_reloaded, mlflow, nibabel, nni, nvimgcodec, onnx, openslide, optuna, pandas, pillow, polygraphy, psutil, pyamg, pybind11, pydicom, pynrrd, pynvml, pyyaml, requests, segment_anything, scipy, skimage, tensorboard, tensorboardX, tifffile, torchio, torchvision, tqdm, transformers, zarr ``` -which correspond to the packages: `clearml`, `cucim` (`cucim-cu12` or `cucim-cu13`), `cupy-cuda13x`, `einops`, `fire`, `gdown`, `h5py`, `huggingface_hub`, `nvsubquadratic`, `omegaconf`, `pytorch-ignite`, `imagecodecs`, `itk`, `jsonschema`, `lmdb`, `lpips`, `matplotlib`, `MetricsReloaded`, `mlflow`, `nibabel`, `nni`, `filelock`, `nvidia-nvimgcodec-cu13`, `onnx`, `onnxruntime`, `onnx_graphsurgeon`, `onnxscript`, `openslide-python`, `openslide-bin`, `optuna`, `pandas`, `pillow`, `polygraphy`, `psutil`, `pyamg`, `pybind11`, `pydicom`, `pynrrd`, `nvidia-ml-py`, `pyyaml`, `requests`, `segment_anything`, `scipy`, `scikit-image`, `tensorboard`, `tensorboardX`, `tifffile`, `torchio`, `torchvision`, `tqdm`, `transformers`, `zarr`. +which correspond to the packages: `clearml`, `cucim` (`cucim-cu12` or `cucim-cu13`), `cupy-cuda13x`, `einops`, `fire`, `gdown`, `h5py`, `huggingface_hub`, `nvsubquadratic`, `omegaconf`, `pytorch-ignite`, `imagecodecs`, `itk`, `jsonschema`, `lmdb`, `matplotlib`, `MetricsReloaded`, `mlflow`, `nibabel`, `nni`, `filelock`, `nvidia-nvimgcodec-cu13`, `onnx`, `onnxruntime`, `onnx_graphsurgeon`, `onnxscript`, `openslide-python`, `openslide-bin`, `optuna`, `pandas`, `pillow`, `polygraphy`, `psutil`, `pyamg`, `pybind11`, `pydicom`, `pynrrd`, `nvidia-ml-py`, `pyyaml`, `requests`, `segment_anything`, `scipy`, `scikit-image`, `tensorboard`, `tensorboardX`, `tifffile`, `torchio`, `torchvision`, `tqdm`, `transformers`, `zarr`. + +The AlexNet, VGG, and SqueezeNet options in `PerceptualLoss` require `torchvision` +(`pip install "monai[torchvision]"`). MONAI includes the LPIPS calibration weights; +the external `lpips` package is no longer required. ImageNet feature weights are +downloaded by Torchvision on first use. +The existing `monai[lpips]` extra is retained as an alias for `monai[torchvision]`. Almost all of these can be installed together with the `all` option. For development on MONAI, this should be accompanied by `testing` which will install the testing static checking packages. Cupy and `nvimgcodec` are omitted from `all` since the choice between Cuda 12 and 13 versions of the libraries can't be resolved when installing and must be manually installed. diff --git a/monai/losses/_perceptual.py b/monai/losses/_perceptual.py new file mode 100644 index 00000000000..75bc6278cc6 --- /dev/null +++ b/monai/losses/_perceptual.py @@ -0,0 +1,140 @@ +# Copyright (c) MONAI Consortium +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Adapted from richzhang/PerceptualSimilarity, commit +# 082bb24f84c091ea94de2867d34c4544f68e0963 (lpips/lpips.py and pretrained_networks.py). +# Copyright (c) 2018, Richard Zhang, Phillip Isola, Alexei A. Efros, +# Eli Shechtman, Oliver Wang. All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are met: +# +# * Redistributions of source code must retain the above copyright notice, this +# list of conditions and the following disclaimer. +# * Redistributions in binary form must reproduce the above copyright notice, +# this list of conditions and the following disclaimer in the documentation +# and/or other materials provided with the distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + +from __future__ import annotations + +from pathlib import Path + +import torch +from torch import nn + +from monai.utils import optional_import + +torchvision, _ = optional_import("torchvision") + + +class _ScalingLayer(nn.Module): + def __init__(self) -> None: + super().__init__() + self.register_buffer("shift", torch.tensor([-0.030, -0.088, -0.188])[None, :, None, None]) + self.register_buffer("scale", torch.tensor([0.458, 0.448, 0.450])[None, :, None, None]) + + def forward(self, input: torch.Tensor) -> torch.Tensor: + return (input - self.shift) / self.scale + + +class _LPIPSFeatures(nn.Module): + def __init__(self, features: nn.Sequential, endpoints: tuple[int, ...]) -> None: + super().__init__() + self.num_slices = len(endpoints) + start = 0 + for index, end in enumerate(endpoints, 1): + # Keep the original names so existing PerceptualLoss checkpoints can be loaded. + block = nn.Sequential() + for layer in range(start, end): + block.add_module(str(layer), features[layer]) + self.add_module(f"slice{index}", block) + start = end + self.requires_grad_(False) + + def forward(self, input: torch.Tensor) -> tuple[torch.Tensor, ...]: + outputs = [] + for index in range(1, self.num_slices + 1): + input = getattr(self, f"slice{index}")(input) + outputs.append(input) + return tuple(outputs) + + +class _NetLinLayer(nn.Module): + def __init__(self, channels: int) -> None: + super().__init__() + self.model = nn.Sequential(nn.Dropout(), nn.Conv2d(channels, 1, 1, bias=False)) + + def forward(self, input: torch.Tensor) -> torch.Tensor: + return self.model(input) + + +class LPIPS(nn.Module): + """Internal LPIPS v0.1 implementation for :class:`monai.losses.PerceptualLoss`. + + ImageNet feature weights come from Torchvision. ``pretrained`` controls only the + learned linear calibration, matching the original LPIPS constructor. The v0.1 + calibration weights and their license are distributed in the adjacent weights directory. + """ + + def __init__(self, pretrained: bool = True, net: str = "alex") -> None: + super().__init__() + networks = { + "alex": ("alexnet", "AlexNet_Weights", (2, 5, 8, 10, 12), (64, 192, 384, 256, 256)), + "vgg": ("vgg16", "VGG16_Weights", (4, 9, 16, 23, 30), (64, 128, 256, 512, 512)), + "squeeze": ( + "squeezenet1_1", + "SqueezeNet1_1_Weights", + (2, 5, 8, 10, 11, 12, 13), + (64, 128, 256, 384, 384, 512, 512), + ), + } + if net not in networks: + raise ValueError(f"Unsupported LPIPS network: {net}.") + factory, weights, endpoints, channels = networks[net] + self.scaling_layer = _ScalingLayer() + backbone = getattr(torchvision.models, factory)(weights=getattr(torchvision.models, weights).IMAGENET1K_V1) + self.net = _LPIPSFeatures(backbone.features, endpoints) + layers = [] + for index, channel_count in enumerate(channels): + layer = _NetLinLayer(channel_count) + self.add_module(f"lin{index}", layer) + layers.append(layer) + self.lins = nn.ModuleList(layers) + if pretrained: + path = Path(__file__).with_name("weights") / f"{net}.pth" + self.load_state_dict(torch.load(path, map_location="cpu", weights_only=True), strict=False) + self.eval() + + def forward(self, input: torch.Tensor, target: torch.Tensor) -> torch.Tensor: + features_input = self.net(self.scaling_layer(input)) + features_target = self.net(self.scaling_layer(target)) + results = [] + for layer, source, reference in zip(self.lins, features_input, features_target): + # LPIPS places epsilon outside the square root. Keep its original normalization + # rather than the different normalization used by the other perceptual networks. + source = source / (torch.sqrt(torch.sum(source**2, dim=1, keepdim=True)) + 1e-10) + reference = reference / (torch.sqrt(torch.sum(reference**2, dim=1, keepdim=True)) + 1e-10) + results.append(layer((source - reference) ** 2).mean([2, 3], keepdim=True)) + result = results[0] + for value in results[1:]: + result = result + value + return result diff --git a/monai/losses/perceptual.py b/monai/losses/perceptual.py index 6c0608f605a..556eb7b189c 100644 --- a/monai/losses/perceptual.py +++ b/monai/losses/perceptual.py @@ -16,6 +16,7 @@ import torch import torch.nn as nn +from monai.losses._perceptual import LPIPS from monai.utils import optional_import from monai.utils.enums import StrEnum @@ -24,7 +25,6 @@ ("medicalnet_resnet10_23datasets", "medicalnet_resnet50_23datasets", "radimagenet_resnet50") ) -LPIPS, _ = optional_import("lpips", name="LPIPS") torchvision, _ = optional_import("torchvision") @@ -67,8 +67,9 @@ class PerceptualLoss(nn.Module): is_fake_3d: if True use 2.5D approach for a 3D perceptual loss. fake_3d_ratio: ratio of how many slices per axis are used in the 2.5D approach. cache_dir: path to cache directory to save the pretrained network weights. - pretrained: whether to load pretrained weights. This argument only works when using networks from - LIPIS or Torchvision. Defaults to ``True``. + pretrained: whether to load pretrained weights. For "alex", "vgg", and "squeeze", this controls + the LPIPS linear calibration weights; the feature network always uses ImageNet weights from + Torchvision. For "resnet50", this controls the feature network weights. Defaults to ``True``. pretrained_path: if `pretrained` is `True`, users can specify a weights file to be loaded via using this argument. This argument only works when ``"network_type"`` is "resnet50". Defaults to `None`. @@ -151,8 +152,7 @@ def __init__( pretrained_state_dict_key=pretrained_state_dict_key, ) else: - # VGG, AlexNet and SqueezeNet are independently handled by LPIPS. - self.perceptual_function = LPIPS(pretrained=pretrained, net=network_type, verbose=False) + self.perceptual_function = LPIPS(pretrained=pretrained, net=network_type) self.is_fake_3d = is_fake_3d self.fake_3d_ratio = fake_3d_ratio diff --git a/monai/losses/weights/LICENSE.LPIPS b/monai/losses/weights/LICENSE.LPIPS new file mode 100644 index 00000000000..842c363a7fc --- /dev/null +++ b/monai/losses/weights/LICENSE.LPIPS @@ -0,0 +1,23 @@ +Copyright (c) 2018, Richard Zhang, Phillip Isola, Alexei A. Efros, Eli Shechtman, Oliver Wang +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + +* Redistributions of source code must retain the above copyright notice, this + list of conditions and the following disclaimer. + +* Redistributions in binary form must reproduce the above copyright notice, + this list of conditions and the following disclaimer in the documentation + and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" +AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/monai/losses/weights/README.md b/monai/losses/weights/README.md new file mode 100644 index 00000000000..27fe51f32e4 --- /dev/null +++ b/monai/losses/weights/README.md @@ -0,0 +1,16 @@ +# LPIPS calibration weights + +These are the unmodified LPIPS v0.1 linear calibration weights from +[richzhang/PerceptualSimilarity](https://github.com/richzhang/PerceptualSimilarity/tree/082bb24f84c091ea94de2867d34c4544f68e0963/lpips/weights/v0.1), +commit `082bb24f84c091ea94de2867d34c4544f68e0963`. +The copyright notice, redistribution conditions, and disclaimer are in +[LICENSE.LPIPS](LICENSE.LPIPS). + +These small calibration layers are separate from the ImageNet feature networks, +whose pretrained weights are provided by Torchvision. + +| File | SHA-256 | +| --- | --- | +| alex.pth | df73285e35b22355a2df87cdb6b70b343713b667eddbda73e1977e0c860835c0 | +| vgg.pth | a78928a0af1e5f0fcb1f3b9e8f8c3a2a5a3de244d830ad5c1feddc79b8432868 | +| squeeze.pth | 4a5350f23600cb79923ce65bb07cbf57dca461329894153e05a1346bd531cf76 | diff --git a/monai/losses/weights/alex.pth b/monai/losses/weights/alex.pth new file mode 100644 index 0000000000000000000000000000000000000000..1df9dfe62abb1fc89cc7f82b4e5fe886c979708e GIT binary patch literal 6009 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 PyEGODb&D{1dnW!5&PYuU literal 0 HcmV?d00001 diff --git a/pyproject.toml b/pyproject.toml index b466ae7533d..16025ea6b36 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,7 @@ description = "AI Toolkit for Healthcare Imaging" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.10" license = "Apache-2.0" -license-files = ["LICENSE"] +license-files = ["LICENSE", "monai/losses/weights/LICENSE.LPIPS"] authors = [{ name = "MONAI Consortium", email = "monai.contact@gmail.com" }] classifiers = [ "Intended Audience :: Developers", @@ -69,7 +69,6 @@ all = [ "itk>=5.2", "jsonschema", "lmdb", - "lpips==0.1.4", "matplotlib>=3.6.3", "MetricsReloaded @ git+https://github.com/Project-MONAI/MetricsReloaded@monai-support", "mlflow>=3.15.2", @@ -124,7 +123,7 @@ imagecodecs = ["imagecodecs; platform_system == 'Linux' or platform_system == 'D itk = ["itk>=5.2"] jsonschema = ["jsonschema"] lmdb = ["lmdb"] -lpips = ["lpips==0.1.4"] +lpips = ["torchvision"] # compatibility extra; LPIPS is implemented within MONAI matplotlib = ["matplotlib>=3.6.3"] # per #5882 this requirement must be on one line to get removed by sed in weekly-preview.yml metrics_reloaded = ["MetricsReloaded @ git+https://github.com/Project-MONAI/MetricsReloaded@monai-support"] diff --git a/setup.py b/setup.py index 73ff3460341..aa3aeea8394 100644 --- a/setup.py +++ b/setup.py @@ -165,6 +165,6 @@ def get_cmds(): cmdclass=get_cmds(), packages=find_packages(exclude=("docs", "examples", "tests", "tests.*")), zip_safe=False, - package_data=cast(Any, {"monai": ["py.typed", *jit_extension_source]}), + package_data=cast(Any, {"monai": ["py.typed", "losses/weights/*", *jit_extension_source]}), ext_modules=get_extensions(), ) diff --git a/tests/losses/test_perceptual_lpips.py b/tests/losses/test_perceptual_lpips.py new file mode 100644 index 00000000000..0db3993d31d --- /dev/null +++ b/tests/losses/test_perceptual_lpips.py @@ -0,0 +1,80 @@ +# Copyright (c) MONAI Consortium +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import annotations + +import unittest +from unittest.mock import patch + +import torch +from parameterized import parameterized + +from monai.losses import PerceptualLoss +from monai.utils import optional_import +from tests.test_utils import skip_if_quick + +torchvision, has_torchvision = optional_import("torchvision") + + +@unittest.skipUnless(has_torchvision, "Requires torchvision") +@skip_if_quick +class TestPerceptualLPIPS(unittest.TestCase): + @parameterized.expand([("alex", "alexnet"), ("vgg", "vgg16"), ("squeeze", "squeezenet1_1")]) + def test_distance_and_gradient_without_lpips(self, net, factory_name): + # Only replace external weight downloading; use the actual Torchvision networks. + factory = getattr(torchvision.models, factory_name) + with patch.object(torchvision.models, factory_name, side_effect=lambda **kwargs: factory(weights=None)): + loss = PerceptualLoss(spatial_dims=2, network_type=net) + + model = loss.perceptual_function + self.assertFalse(model.training) + self.assertTrue(all(not p.requires_grad for p in model.net.parameters())) + self.assertTrue(all(p.requires_grad for p in model.lins.parameters())) + for channels in (1, 3): + with self.subTest(channels=channels): + source = torch.rand(2, channels, 64, 64, requires_grad=True) + target = torch.rand_like(source) + self.assertEqual(loss(source, source).item(), 0.0) + distance = model(source, target) + self.assertEqual(distance.shape, (2, 1, 1, 1)) + self.assertTrue(torch.all(distance > 0)) + torch.testing.assert_close(distance, model(target, source)) + torch.testing.assert_close(loss(source, target), distance.mean()) + distance.mean().backward() + self.assertTrue(torch.isfinite(source.grad).all()) + self.assertGreater(source.grad.abs().sum().item(), 0) + + # Existing checkpoints contain both names for the same registered calibration layers. + state = model.state_dict() + self.assertIn("net.slice1.0.weight", state) + torch.testing.assert_close(state["lin0.model.1.weight"], state["lins.0.model.1.weight"]) + self.assertTrue(all(torch.isfinite(value).all() for value in state.values())) + + def test_fake_3d_matches_three_axes(self): + factory = torchvision.models.squeezenet1_1 + with patch.object(torchvision.models, "squeezenet1_1", side_effect=lambda **kwargs: factory(weights=None)): + loss = PerceptualLoss(spatial_dims=3, network_type="squeeze", fake_3d_ratio=1.0) + source = torch.rand(1, 1, 32, 32, 32, requires_grad=True) + target = torch.rand_like(source) + expected = sum( + loss.perceptual_function( + source.movedim(axis, 1).reshape(-1, 1, 32, 32), target.movedim(axis, 1).reshape(-1, 1, 32, 32) + ).mean() + for axis in (2, 3, 4) + ) + actual = loss(source, target) + torch.testing.assert_close(actual, expected) + actual.backward() + self.assertTrue(torch.isfinite(source.grad).all()) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/min_tests.py b/tests/min_tests.py index 25a42fe4b5d..0dcbe498169 100644 --- a/tests/min_tests.py +++ b/tests/min_tests.py @@ -214,6 +214,7 @@ def run_testsuit(): "test_bundle_workflow", "test_zarr_avg_merger", "test_perceptual_loss", + "test_perceptual_lpips", "test_ultrasound_confidence_map_transform", "test_vista3d_utils", "test_vista3d_transforms", From 7dc1b10be3a88977940bdbe06b9763f5d7872f8a Mon Sep 17 00:00:00 2001 From: oynal Date: Tue, 17 Nov 2026 12:30:54 +0800 Subject: [PATCH 2/5] test: cover LPIPS calibration and checkpoint compatibility Verify both calibration settings, ImageNet backbone selection, and strict loading of legacy PerceptualLoss checkpoints using an upstream key/shape manifest. Tests reject three temporary mutations and pass from a clean staged snapshot. Assisted-by: Codex Signed-off-by: oynal --- tests/losses/test_perceptual_lpips.py | 51 +- tests/testing_data/lpips_v0_1_state_dict.json | 638 ++++++++++++++++++ 2 files changed, 684 insertions(+), 5 deletions(-) create mode 100644 tests/testing_data/lpips_v0_1_state_dict.json diff --git a/tests/losses/test_perceptual_lpips.py b/tests/losses/test_perceptual_lpips.py index 0db3993d31d..22c4878f940 100644 --- a/tests/losses/test_perceptual_lpips.py +++ b/tests/losses/test_perceptual_lpips.py @@ -11,7 +11,9 @@ from __future__ import annotations +import json import unittest +from pathlib import Path from unittest.mock import patch import torch @@ -27,17 +29,35 @@ @unittest.skipUnless(has_torchvision, "Requires torchvision") @skip_if_quick class TestPerceptualLPIPS(unittest.TestCase): - @parameterized.expand([("alex", "alexnet"), ("vgg", "vgg16"), ("squeeze", "squeezenet1_1")]) - def test_distance_and_gradient_without_lpips(self, net, factory_name): + @parameterized.expand( + [ + (net, factory, weights, pretrained) + for net, factory, weights in ( + ("alex", "alexnet", "AlexNet_Weights"), + ("vgg", "vgg16", "VGG16_Weights"), + ("squeeze", "squeezenet1_1", "SqueezeNet1_1_Weights"), + ) + for pretrained in (True, False) + ] + ) + def test_distance_and_gradient_without_lpips(self, net, factory_name, weights_name, pretrained): # Only replace external weight downloading; use the actual Torchvision networks. factory = getattr(torchvision.models, factory_name) - with patch.object(torchvision.models, factory_name, side_effect=lambda **kwargs: factory(weights=None)): - loss = PerceptualLoss(spatial_dims=2, network_type=net) + torch.manual_seed(9284) + with patch.object( + torchvision.models, factory_name, side_effect=lambda **kwargs: factory(weights=None) + ) as create_backbone: + loss = PerceptualLoss(spatial_dims=2, network_type=net, pretrained=pretrained) + create_backbone.assert_called_once_with(weights=getattr(torchvision.models, weights_name).IMAGENET1K_V1) model = loss.perceptual_function self.assertFalse(model.training) self.assertTrue(all(not p.requires_grad for p in model.net.parameters())) self.assertTrue(all(p.requires_grad for p in model.lins.parameters())) + calibration_path = Path(__file__).parents[2] / "monai" / "losses" / "weights" / f"{net}.pth" + calibrated_state = torch.load(calibration_path, map_location="cpu", weights_only=True) + for key, value in calibrated_state.items(): + self.assertEqual(torch.equal(model.state_dict()[key], value), pretrained) for channels in (1, 3): with self.subTest(channels=channels): source = torch.rand(2, channels, 64, 64, requires_grad=True) @@ -45,7 +65,12 @@ def test_distance_and_gradient_without_lpips(self, net, factory_name): self.assertEqual(loss(source, source).item(), 0.0) distance = model(source, target) self.assertEqual(distance.shape, (2, 1, 1, 1)) - self.assertTrue(torch.all(distance > 0)) + self.assertTrue(torch.isfinite(distance).all()) + if pretrained: + self.assertTrue(torch.all(distance > 0)) + else: + # Random calibration layers need not define a nonnegative metric. + self.assertTrue(torch.all(distance != 0)) torch.testing.assert_close(distance, model(target, source)) torch.testing.assert_close(loss(source, target), distance.mean()) distance.mean().backward() @@ -58,6 +83,22 @@ def test_distance_and_gradient_without_lpips(self, net, factory_name): torch.testing.assert_close(state["lin0.model.1.weight"], state["lins.0.model.1.weight"]) self.assertTrue(all(torch.isfinite(value).all() for value in state.values())) + @parameterized.expand([("alex", "alexnet"), ("vgg", "vgg16"), ("squeeze", "squeezenet1_1")]) + def test_load_legacy_state_dict(self, net, factory_name): + # Captured from unmodified LPIPS v0.1, independent of MONAI's module registration. + manifest_path = Path(__file__).parents[1] / "testing_data" / "lpips_v0_1_state_dict.json" + manifest = json.loads(manifest_path.read_text())["networks"][net] + factory = getattr(torchvision.models, factory_name) + with patch.object(torchvision.models, factory_name, side_effect=lambda **kwargs: factory(weights=None)): + loss = PerceptualLoss(spatial_dims=2, network_type=net) + legacy_state = {f"perceptual_function.{key}": torch.full(shape, 0.125) for key, shape in manifest.items()} + loss.load_state_dict(legacy_state, strict=True) + self.assertEqual(set(loss.state_dict()), set(legacy_state)) + for key, value in loss.state_dict().items(): + with self.subTest(key=key): + self.assertEqual(tuple(value.shape), tuple(manifest[key.removeprefix("perceptual_function.")])) + torch.testing.assert_close(value, legacy_state[key], rtol=0, atol=0) + def test_fake_3d_matches_three_axes(self): factory = torchvision.models.squeezenet1_1 with patch.object(torchvision.models, "squeezenet1_1", side_effect=lambda **kwargs: factory(weights=None)): diff --git a/tests/testing_data/lpips_v0_1_state_dict.json b/tests/testing_data/lpips_v0_1_state_dict.json new file mode 100644 index 00000000000..db018e081f9 --- /dev/null +++ b/tests/testing_data/lpips_v0_1_state_dict.json @@ -0,0 +1,638 @@ +{ + "source": "richzhang/PerceptualSimilarity@082bb24f84c091ea94de2867d34c4544f68e0963", + "networks": { + "alex": { + "scaling_layer.shift": [ + 1, + 3, + 1, + 1 + ], + "scaling_layer.scale": [ + 1, + 3, + 1, + 1 + ], + "net.slice1.0.weight": [ + 64, + 3, + 11, + 11 + ], + "net.slice1.0.bias": [ + 64 + ], + "net.slice2.3.weight": [ + 192, + 64, + 5, + 5 + ], + "net.slice2.3.bias": [ + 192 + ], + "net.slice3.6.weight": [ + 384, + 192, + 3, + 3 + ], + "net.slice3.6.bias": [ + 384 + ], + "net.slice4.8.weight": [ + 256, + 384, + 3, + 3 + ], + "net.slice4.8.bias": [ + 256 + ], + "net.slice5.10.weight": [ + 256, + 256, + 3, + 3 + ], + "net.slice5.10.bias": [ + 256 + ], + "lin0.model.1.weight": [ + 1, + 64, + 1, + 1 + ], + "lin1.model.1.weight": [ + 1, + 192, + 1, + 1 + ], + "lin2.model.1.weight": [ + 1, + 384, + 1, + 1 + ], + "lin3.model.1.weight": [ + 1, + 256, + 1, + 1 + ], + "lin4.model.1.weight": [ + 1, + 256, + 1, + 1 + ], + "lins.0.model.1.weight": [ + 1, + 64, + 1, + 1 + ], + "lins.1.model.1.weight": [ + 1, + 192, + 1, + 1 + ], + "lins.2.model.1.weight": [ + 1, + 384, + 1, + 1 + ], + "lins.3.model.1.weight": [ + 1, + 256, + 1, + 1 + ], + "lins.4.model.1.weight": [ + 1, + 256, + 1, + 1 + ] + }, + "vgg": { + "scaling_layer.shift": [ + 1, + 3, + 1, + 1 + ], + "scaling_layer.scale": [ + 1, + 3, + 1, + 1 + ], + "net.slice1.0.weight": [ + 64, + 3, + 3, + 3 + ], + "net.slice1.0.bias": [ + 64 + ], + "net.slice1.2.weight": [ + 64, + 64, + 3, + 3 + ], + "net.slice1.2.bias": [ + 64 + ], + "net.slice2.5.weight": [ + 128, + 64, + 3, + 3 + ], + "net.slice2.5.bias": [ + 128 + ], + "net.slice2.7.weight": [ + 128, + 128, + 3, + 3 + ], + "net.slice2.7.bias": [ + 128 + ], + "net.slice3.10.weight": [ + 256, + 128, + 3, + 3 + ], + "net.slice3.10.bias": [ + 256 + ], + "net.slice3.12.weight": [ + 256, + 256, + 3, + 3 + ], + "net.slice3.12.bias": [ + 256 + ], + "net.slice3.14.weight": [ + 256, + 256, + 3, + 3 + ], + "net.slice3.14.bias": [ + 256 + ], + "net.slice4.17.weight": [ + 512, + 256, + 3, + 3 + ], + "net.slice4.17.bias": [ + 512 + ], + "net.slice4.19.weight": [ + 512, + 512, + 3, + 3 + ], + "net.slice4.19.bias": [ + 512 + ], + "net.slice4.21.weight": [ + 512, + 512, + 3, + 3 + ], + "net.slice4.21.bias": [ + 512 + ], + "net.slice5.24.weight": [ + 512, + 512, + 3, + 3 + ], + "net.slice5.24.bias": [ + 512 + ], + "net.slice5.26.weight": [ + 512, + 512, + 3, + 3 + ], + "net.slice5.26.bias": [ + 512 + ], + "net.slice5.28.weight": [ + 512, + 512, + 3, + 3 + ], + "net.slice5.28.bias": [ + 512 + ], + "lin0.model.1.weight": [ + 1, + 64, + 1, + 1 + ], + "lin1.model.1.weight": [ + 1, + 128, + 1, + 1 + ], + "lin2.model.1.weight": [ + 1, + 256, + 1, + 1 + ], + "lin3.model.1.weight": [ + 1, + 512, + 1, + 1 + ], + "lin4.model.1.weight": [ + 1, + 512, + 1, + 1 + ], + "lins.0.model.1.weight": [ + 1, + 64, + 1, + 1 + ], + "lins.1.model.1.weight": [ + 1, + 128, + 1, + 1 + ], + "lins.2.model.1.weight": [ + 1, + 256, + 1, + 1 + ], + "lins.3.model.1.weight": [ + 1, + 512, + 1, + 1 + ], + "lins.4.model.1.weight": [ + 1, + 512, + 1, + 1 + ] + }, + "squeeze": { + "scaling_layer.shift": [ + 1, + 3, + 1, + 1 + ], + "scaling_layer.scale": [ + 1, + 3, + 1, + 1 + ], + "net.slice1.0.weight": [ + 64, + 3, + 3, + 3 + ], + "net.slice1.0.bias": [ + 64 + ], + "net.slice2.3.squeeze.weight": [ + 16, + 64, + 1, + 1 + ], + "net.slice2.3.squeeze.bias": [ + 16 + ], + "net.slice2.3.expand1x1.weight": [ + 64, + 16, + 1, + 1 + ], + "net.slice2.3.expand1x1.bias": [ + 64 + ], + "net.slice2.3.expand3x3.weight": [ + 64, + 16, + 3, + 3 + ], + "net.slice2.3.expand3x3.bias": [ + 64 + ], + "net.slice2.4.squeeze.weight": [ + 16, + 128, + 1, + 1 + ], + "net.slice2.4.squeeze.bias": [ + 16 + ], + "net.slice2.4.expand1x1.weight": [ + 64, + 16, + 1, + 1 + ], + "net.slice2.4.expand1x1.bias": [ + 64 + ], + "net.slice2.4.expand3x3.weight": [ + 64, + 16, + 3, + 3 + ], + "net.slice2.4.expand3x3.bias": [ + 64 + ], + "net.slice3.6.squeeze.weight": [ + 32, + 128, + 1, + 1 + ], + "net.slice3.6.squeeze.bias": [ + 32 + ], + "net.slice3.6.expand1x1.weight": [ + 128, + 32, + 1, + 1 + ], + "net.slice3.6.expand1x1.bias": [ + 128 + ], + "net.slice3.6.expand3x3.weight": [ + 128, + 32, + 3, + 3 + ], + "net.slice3.6.expand3x3.bias": [ + 128 + ], + "net.slice3.7.squeeze.weight": [ + 32, + 256, + 1, + 1 + ], + "net.slice3.7.squeeze.bias": [ + 32 + ], + "net.slice3.7.expand1x1.weight": [ + 128, + 32, + 1, + 1 + ], + "net.slice3.7.expand1x1.bias": [ + 128 + ], + "net.slice3.7.expand3x3.weight": [ + 128, + 32, + 3, + 3 + ], + "net.slice3.7.expand3x3.bias": [ + 128 + ], + "net.slice4.9.squeeze.weight": [ + 48, + 256, + 1, + 1 + ], + "net.slice4.9.squeeze.bias": [ + 48 + ], + "net.slice4.9.expand1x1.weight": [ + 192, + 48, + 1, + 1 + ], + "net.slice4.9.expand1x1.bias": [ + 192 + ], + "net.slice4.9.expand3x3.weight": [ + 192, + 48, + 3, + 3 + ], + "net.slice4.9.expand3x3.bias": [ + 192 + ], + "net.slice5.10.squeeze.weight": [ + 48, + 384, + 1, + 1 + ], + "net.slice5.10.squeeze.bias": [ + 48 + ], + "net.slice5.10.expand1x1.weight": [ + 192, + 48, + 1, + 1 + ], + "net.slice5.10.expand1x1.bias": [ + 192 + ], + "net.slice5.10.expand3x3.weight": [ + 192, + 48, + 3, + 3 + ], + "net.slice5.10.expand3x3.bias": [ + 192 + ], + "net.slice6.11.squeeze.weight": [ + 64, + 384, + 1, + 1 + ], + "net.slice6.11.squeeze.bias": [ + 64 + ], + "net.slice6.11.expand1x1.weight": [ + 256, + 64, + 1, + 1 + ], + "net.slice6.11.expand1x1.bias": [ + 256 + ], + "net.slice6.11.expand3x3.weight": [ + 256, + 64, + 3, + 3 + ], + "net.slice6.11.expand3x3.bias": [ + 256 + ], + "net.slice7.12.squeeze.weight": [ + 64, + 512, + 1, + 1 + ], + "net.slice7.12.squeeze.bias": [ + 64 + ], + "net.slice7.12.expand1x1.weight": [ + 256, + 64, + 1, + 1 + ], + "net.slice7.12.expand1x1.bias": [ + 256 + ], + "net.slice7.12.expand3x3.weight": [ + 256, + 64, + 3, + 3 + ], + "net.slice7.12.expand3x3.bias": [ + 256 + ], + "lin0.model.1.weight": [ + 1, + 64, + 1, + 1 + ], + "lin1.model.1.weight": [ + 1, + 128, + 1, + 1 + ], + "lin2.model.1.weight": [ + 1, + 256, + 1, + 1 + ], + "lin3.model.1.weight": [ + 1, + 384, + 1, + 1 + ], + "lin4.model.1.weight": [ + 1, + 384, + 1, + 1 + ], + "lin5.model.1.weight": [ + 1, + 512, + 1, + 1 + ], + "lin6.model.1.weight": [ + 1, + 512, + 1, + 1 + ], + "lins.0.model.1.weight": [ + 1, + 64, + 1, + 1 + ], + "lins.1.model.1.weight": [ + 1, + 128, + 1, + 1 + ], + "lins.2.model.1.weight": [ + 1, + 256, + 1, + 1 + ], + "lins.3.model.1.weight": [ + 1, + 384, + 1, + 1 + ], + "lins.4.model.1.weight": [ + 1, + 384, + 1, + 1 + ], + "lins.5.model.1.weight": [ + 1, + 512, + 1, + 1 + ], + "lins.6.model.1.weight": [ + 1, + 512, + 1, + 1 + ] + } + } +} From 8b447f272c28cb0db00a17e304ddb16f2fe9891b Mon Sep 17 00:00:00 2001 From: oynal Date: Tue, 17 Nov 2026 13:20:58 +0800 Subject: [PATCH 3/5] docs: document LPIPS helpers and validation Describe helper inputs, outputs, calibration flags, and unsupported network errors. Explain the shared legacy calibration registrations and add a focused validation regression test. Assisted-by: Codex Signed-off-by: oynal --- monai/losses/_perceptual.py | 81 +++++++++++++++++++++++++++ tests/losses/test_perceptual_lpips.py | 10 ++++ 2 files changed, 91 insertions(+) diff --git a/monai/losses/_perceptual.py b/monai/losses/_perceptual.py index 75bc6278cc6..7c20e2e5cc6 100644 --- a/monai/losses/_perceptual.py +++ b/monai/losses/_perceptual.py @@ -47,17 +47,41 @@ class _ScalingLayer(nn.Module): + """Apply the fixed RGB shift and scale used by LPIPS v0.1.""" + def __init__(self) -> None: + """Register the channel-wise shift and scale as buffers.""" super().__init__() self.register_buffer("shift", torch.tensor([-0.030, -0.088, -0.188])[None, :, None, None]) self.register_buffer("scale", torch.tensor([0.458, 0.448, 0.450])[None, :, None, None]) def forward(self, input: torch.Tensor) -> torch.Tensor: + """Scale an image batch, broadcasting grayscale inputs to RGB. + + Args: + input: Image tensor of shape ``(B, C, H, W)``, with one or three channels. + + Returns: + Scaled image tensor of shape ``(B, 3, H, W)``. + """ return (input - self.shift) / self.scale class _LPIPSFeatures(nn.Module): + """Extract frozen Torchvision features using legacy LPIPS slice names. + + Args: + features: Ordered feature layers from a Torchvision backbone. + endpoints: Exclusive layer indices at which each successive slice ends. + """ + def __init__(self, features: nn.Sequential, endpoints: tuple[int, ...]) -> None: + """Build successive feature slices and freeze their parameters. + + Args: + features: Ordered feature layers from a Torchvision backbone. + endpoints: Exclusive layer indices at which each successive slice ends. + """ super().__init__() self.num_slices = len(endpoints) start = 0 @@ -71,6 +95,14 @@ def __init__(self, features: nn.Sequential, endpoints: tuple[int, ...]) -> None: self.requires_grad_(False) def forward(self, input: torch.Tensor) -> tuple[torch.Tensor, ...]: + """Collect the output of each feature slice. + + Args: + input: Scaled RGB image tensor of shape ``(B, 3, H, W)``. + + Returns: + Feature tensors in slice order, each with shape ``(B, C_i, H_i, W_i)``. + """ outputs = [] for index in range(1, self.num_slices + 1): input = getattr(self, f"slice{index}")(input) @@ -79,11 +111,30 @@ def forward(self, input: torch.Tensor) -> tuple[torch.Tensor, ...]: class _NetLinLayer(nn.Module): + """Calibrate feature differences with Dropout and a bias-free 1x1 convolution. + + Args: + channels: Number of input feature channels. + """ + def __init__(self, channels: int) -> None: + """Initialize a calibration layer. + + Args: + channels: Number of input feature channels. + """ super().__init__() self.model = nn.Sequential(nn.Dropout(), nn.Conv2d(channels, 1, 1, bias=False)) def forward(self, input: torch.Tensor) -> torch.Tensor: + """Compute the calibrated spatial difference map. + + Args: + input: Squared normalized feature differences of shape ``(B, C, H, W)``. + + Returns: + Calibrated difference map of shape ``(B, 1, H, W)``. + """ return self.model(input) @@ -93,9 +144,27 @@ class LPIPS(nn.Module): ImageNet feature weights come from Torchvision. ``pretrained`` controls only the learned linear calibration, matching the original LPIPS constructor. The v0.1 calibration weights and their license are distributed in the adjacent weights directory. + + Args: + pretrained: Whether to load pretrained linear calibration weights. The feature + backbone always uses ImageNet weights, including when this is ``False``. + net: Feature backbone name: ``"alex"``, ``"vgg"``, or ``"squeeze"``. + + Raises: + ValueError: If ``net`` is not a supported feature backbone name. """ def __init__(self, pretrained: bool = True, net: str = "alex") -> None: + """Initialize the ImageNet feature backbone and LPIPS calibration layers. + + Args: + pretrained: Whether to load the bundled linear calibration weights. + This does not change the ImageNet weights used by the feature backbone. + net: Feature backbone name: ``"alex"``, ``"vgg"``, or ``"squeeze"``. + + Raises: + ValueError: If ``net`` is not a supported feature backbone name. + """ super().__init__() networks = { "alex": ("alexnet", "AlexNet_Weights", (2, 5, 8, 10, 12), (64, 192, 384, 256, 256)), @@ -113,6 +182,8 @@ def __init__(self, pretrained: bool = True, net: str = "alex") -> None: self.scaling_layer = _ScalingLayer() backbone = getattr(torchvision.models, factory)(weights=getattr(torchvision.models, weights).IMAGENET1K_V1) self.net = _LPIPSFeatures(backbone.features, endpoints) + # Legacy checkpoints contain both lin{index} and lins.{index} keys, so register + # each calibration layer under both names while sharing the same parameters. layers = [] for index, channel_count in enumerate(channels): layer = _NetLinLayer(channel_count) @@ -125,6 +196,16 @@ def __init__(self, pretrained: bool = True, net: str = "alex") -> None: self.eval() def forward(self, input: torch.Tensor, target: torch.Tensor) -> torch.Tensor: + """Compute one LPIPS distance for each image pair. + + Args: + input: Image tensor of shape ``(B, C, H, W)``, with one or three channels. + target: Reference image tensor with the same shape as ``input``. + + Returns: + Per-image distances of shape ``(B, 1, 1, 1)``, before the outer + ``PerceptualLoss`` reduction. + """ features_input = self.net(self.scaling_layer(input)) features_target = self.net(self.scaling_layer(target)) results = [] diff --git a/tests/losses/test_perceptual_lpips.py b/tests/losses/test_perceptual_lpips.py index 22c4878f940..9a4d805ff91 100644 --- a/tests/losses/test_perceptual_lpips.py +++ b/tests/losses/test_perceptual_lpips.py @@ -20,12 +20,22 @@ from parameterized import parameterized from monai.losses import PerceptualLoss +from monai.losses._perceptual import LPIPS from monai.utils import optional_import from tests.test_utils import skip_if_quick torchvision, has_torchvision = optional_import("torchvision") +class TestPerceptualLPIPSValidation(unittest.TestCase): + """Check argument validation before any optional backbone is constructed.""" + + def test_unsupported_network(self): + """Reject unsupported names before constructing a Torchvision backbone.""" + with self.assertRaisesRegex(ValueError, "Unsupported LPIPS network"): + LPIPS(net="unsupported") + + @unittest.skipUnless(has_torchvision, "Requires torchvision") @skip_if_quick class TestPerceptualLPIPS(unittest.TestCase): From 8d0de533d8de4046ceaa821df6164e2c02880ba4 Mon Sep 17 00:00:00 2001 From: oynal Date: Tue, 17 Nov 2026 21:14:59 +0800 Subject: [PATCH 4/5] Address LPIPS network and checkpoint hosting review Expose perceptual networks in networks/nets, use hashed MONAI Hugging Face calibration downloads with Torch Hub caching, and replace bundled weights with a retained license notice. Use Sequential helpers while preserving chained features and legacy checkpoint keys. Add offline download/cache/integrity tests and public API documentation. Assisted-by: Codex Signed-off-by: oynal --- .gitignore | 1 - MANIFEST.in | 1 - docs/source/installation.md | 10 +- docs/source/networks.rst | 19 +++ monai/losses/perceptual.py | 2 +- monai/losses/weights/README.md | 16 --- monai/losses/weights/alex.pth | Bin 6009 -> 0 bytes monai/losses/weights/squeeze.pth | Bin 10811 -> 0 bytes monai/losses/weights/vgg.pth | Bin 7289 -> 0 bytes .../weights => networks/nets}/LICENSE.LPIPS | 0 monai/networks/nets/__init__.py | 1 + .../nets/perceptual.py} | 102 ++++++++------ pyproject.toml | 2 +- setup.py | 2 +- tests/losses/test_perceptual_lpips.py | 13 +- tests/lpips_test_utils.py | 77 ++++++++++ tests/min_tests.py | 1 + tests/networks/nets/test_perceptual.py | 131 ++++++++++++++++++ 18 files changed, 310 insertions(+), 68 deletions(-) delete mode 100644 monai/losses/weights/README.md delete mode 100644 monai/losses/weights/alex.pth delete mode 100644 monai/losses/weights/squeeze.pth delete mode 100644 monai/losses/weights/vgg.pth rename monai/{losses/weights => networks/nets}/LICENSE.LPIPS (100%) rename monai/{losses/_perceptual.py => networks/nets/perceptual.py} (72%) create mode 100644 tests/lpips_test_utils.py create mode 100644 tests/networks/nets/test_perceptual.py diff --git a/.gitignore b/.gitignore index f74156e3968..d0bdc54018d 100644 --- a/.gitignore +++ b/.gitignore @@ -168,6 +168,5 @@ runs *.gz *.pth -!monai/losses/weights/*.pth *zarr/* diff --git a/MANIFEST.in b/MANIFEST.in index 7d931f3b060..d77d3b5e50a 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,2 @@ recursive-include monai/csrc *.cpp *.cu *.h *.cuh -recursive-include monai/losses/weights *.pth LICENSE.LPIPS README.md prune tests diff --git a/docs/source/installation.md b/docs/source/installation.md index 40d9621a9c3..e02012015a6 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -83,9 +83,13 @@ clearml, cucim, cupy, einops, fire, gdown, h5py, huggingface_hub, hyena, ignite, which correspond to the packages: `clearml`, `cucim` (`cucim-cu12` or `cucim-cu13`), `cupy-cuda13x`, `einops`, `fire`, `gdown`, `h5py`, `huggingface_hub`, `nvsubquadratic`, `omegaconf`, `pytorch-ignite`, `imagecodecs`, `itk`, `jsonschema`, `lmdb`, `matplotlib`, `MetricsReloaded`, `mlflow`, `nibabel`, `nni`, `filelock`, `nvidia-nvimgcodec-cu13`, `onnx`, `onnxruntime`, `onnx_graphsurgeon`, `onnxscript`, `openslide-python`, `openslide-bin`, `optuna`, `pandas`, `pillow`, `polygraphy`, `psutil`, `pyamg`, `pybind11`, `pydicom`, `pynrrd`, `nvidia-ml-py`, `pyyaml`, `requests`, `segment_anything`, `scipy`, `scikit-image`, `tensorboard`, `tensorboardX`, `tifffile`, `torchio`, `torchvision`, `tqdm`, `transformers`, `zarr`. The AlexNet, VGG, and SqueezeNet options in `PerceptualLoss` require `torchvision` -(`pip install "monai[torchvision]"`). MONAI includes the LPIPS calibration weights; -the external `lpips` package is no longer required. ImageNet feature weights are -downloaded by Torchvision on first use. +(`pip install "monai[torchvision]"`). The external `lpips` package is no longer required. +ImageNet feature weights are downloaded by Torchvision. LPIPS calibration weights are +downloaded from the official [MONAI Hugging Face repository](https://huggingface.co/MONAI/checkpoints), +verified with SHA-256, and cached under the Torch Hub `checkpoints` directory on first use. +`PerceptualLoss(cache_dir=...)` selects the Torch Hub cache location for both sets of weights. +With `pretrained=False`, calibration weights are not downloaded; ImageNet feature weights +are still required. The existing `monai[lpips]` extra is retained as an alias for `monai[torchvision]`. Almost all of these can be installed together with the `all` option. For development on MONAI, this should be accompanied by `testing` which will install the testing static checking packages. Cupy and `nvimgcodec` are omitted from `all` since the choice between diff --git a/docs/source/networks.rst b/docs/source/networks.rst index 14cc756d7ad..226a8140055 100644 --- a/docs/source/networks.rst +++ b/docs/source/networks.rst @@ -772,6 +772,25 @@ Nets .. autoclass:: TorchVisionFCModel :members: +`LPIPS` +~~~~~~~ +.. autoclass:: LPIPS + :members: + +`LPIPSFeatures` +~~~~~~~~~~~~~~~ +.. autoclass:: LPIPSFeatures + :members: + +`NetLinLayer` +~~~~~~~~~~~~~ +.. autoclass:: NetLinLayer + +`ScalingLayer` +~~~~~~~~~~~~~~ +.. autoclass:: ScalingLayer + :members: + `MILModel` ~~~~~~~~~~ .. autoclass:: MILModel diff --git a/monai/losses/perceptual.py b/monai/losses/perceptual.py index 556eb7b189c..e9e0bab9b20 100644 --- a/monai/losses/perceptual.py +++ b/monai/losses/perceptual.py @@ -16,7 +16,7 @@ import torch import torch.nn as nn -from monai.losses._perceptual import LPIPS +from monai.networks.nets import LPIPS from monai.utils import optional_import from monai.utils.enums import StrEnum diff --git a/monai/losses/weights/README.md b/monai/losses/weights/README.md deleted file mode 100644 index 27fe51f32e4..00000000000 --- a/monai/losses/weights/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# LPIPS calibration weights - -These are the unmodified LPIPS v0.1 linear calibration weights from -[richzhang/PerceptualSimilarity](https://github.com/richzhang/PerceptualSimilarity/tree/082bb24f84c091ea94de2867d34c4544f68e0963/lpips/weights/v0.1), -commit `082bb24f84c091ea94de2867d34c4544f68e0963`. -The copyright notice, redistribution conditions, and disclaimer are in -[LICENSE.LPIPS](LICENSE.LPIPS). - -These small calibration layers are separate from the ImageNet feature networks, -whose pretrained weights are provided by Torchvision. - -| File | SHA-256 | -| --- | --- | -| alex.pth | df73285e35b22355a2df87cdb6b70b343713b667eddbda73e1977e0c860835c0 | -| vgg.pth | a78928a0af1e5f0fcb1f3b9e8f8c3a2a5a3de244d830ad5c1feddc79b8432868 | -| squeeze.pth | 4a5350f23600cb79923ce65bb07cbf57dca461329894153e05a1346bd531cf76 | diff --git a/monai/losses/weights/alex.pth b/monai/losses/weights/alex.pth deleted file mode 100644 index 1df9dfe62abb1fc89cc7f82b4e5fe886c979708e..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 6009 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 PyEGODb&D{1dnW!5&PYuU diff --git a/monai/losses/weights/LICENSE.LPIPS b/monai/networks/nets/LICENSE.LPIPS similarity index 100% rename from monai/losses/weights/LICENSE.LPIPS rename to monai/networks/nets/LICENSE.LPIPS diff --git a/monai/networks/nets/__init__.py b/monai/networks/nets/__init__.py index 085254f1be1..d3d197c8290 100644 --- a/monai/networks/nets/__init__.py +++ b/monai/networks/nets/__init__.py @@ -97,6 +97,7 @@ from .navit import NaViT from .netadapter import NetAdapter from .patchgan_discriminator import MultiScalePatchDiscriminator, PatchDiscriminator +from .perceptual import LPIPS, LPIPSFeatures, NetLinLayer, ScalingLayer from .quicknat import Quicknat from .regressor import Regressor from .regunet import GlobalNet, LocalNet, RegUNet diff --git a/monai/losses/_perceptual.py b/monai/networks/nets/perceptual.py similarity index 72% rename from monai/losses/_perceptual.py rename to monai/networks/nets/perceptual.py index 7c20e2e5cc6..e7b611f2a38 100644 --- a/monai/losses/_perceptual.py +++ b/monai/networks/nets/perceptual.py @@ -36,17 +36,46 @@ from __future__ import annotations +from collections import OrderedDict from pathlib import Path import torch from torch import nn +from monai.apps.utils import download_url from monai.utils import optional_import torchvision, _ = optional_import("torchvision") - -class _ScalingLayer(nn.Module): +__all__ = ["LPIPS", "LPIPSFeatures", "NetLinLayer", "ScalingLayer"] + +LPIPS_WEIGHTS_URL = "https://huggingface.co/MONAI/checkpoints/resolve/main" +LPIPS_NETWORKS = { + "alex": ( + "alexnet", + "AlexNet_Weights", + (2, 5, 8, 10, 12), + (64, 192, 384, 256, 256), + "df73285e35b22355a2df87cdb6b70b343713b667eddbda73e1977e0c860835c0", + ), + "vgg": ( + "vgg16", + "VGG16_Weights", + (4, 9, 16, 23, 30), + (64, 128, 256, 512, 512), + "a78928a0af1e5f0fcb1f3b9e8f8c3a2a5a3de244d830ad5c1feddc79b8432868", + ), + "squeeze": ( + "squeezenet1_1", + "SqueezeNet1_1_Weights", + (2, 5, 8, 10, 11, 12, 13), + (64, 128, 256, 384, 384, 512, 512), + "4a5350f23600cb79923ce65bb07cbf57dca461329894153e05a1346bd531cf76", + ), +} + + +class ScalingLayer(nn.Module): """Apply the fixed RGB shift and scale used by LPIPS v0.1.""" def __init__(self) -> None: @@ -67,7 +96,7 @@ def forward(self, input: torch.Tensor) -> torch.Tensor: return (input - self.shift) / self.scale -class _LPIPSFeatures(nn.Module): +class LPIPSFeatures(nn.Sequential): """Extract frozen Torchvision features using legacy LPIPS slice names. Args: @@ -82,16 +111,16 @@ def __init__(self, features: nn.Sequential, endpoints: tuple[int, ...]) -> None: features: Ordered feature layers from a Torchvision backbone. endpoints: Exclusive layer indices at which each successive slice ends. """ - super().__init__() - self.num_slices = len(endpoints) + slices: OrderedDict[str, nn.Module] = OrderedDict() start = 0 for index, end in enumerate(endpoints, 1): # Keep the original names so existing PerceptualLoss checkpoints can be loaded. block = nn.Sequential() for layer in range(start, end): block.add_module(str(layer), features[layer]) - self.add_module(f"slice{index}", block) + slices[f"slice{index}"] = block start = end + super().__init__(slices) self.requires_grad_(False) def forward(self, input: torch.Tensor) -> tuple[torch.Tensor, ...]: @@ -104,13 +133,14 @@ def forward(self, input: torch.Tensor) -> tuple[torch.Tensor, ...]: Feature tensors in slice order, each with shape ``(B, C_i, H_i, W_i)``. """ outputs = [] - for index in range(1, self.num_slices + 1): - input = getattr(self, f"slice{index}")(input) + for layer in self: + # Each slice consumes the preceding features, not the original RGB input. + input = layer(input) outputs.append(input) return tuple(outputs) -class _NetLinLayer(nn.Module): +class NetLinLayer(nn.Sequential): """Calibrate feature differences with Dropout and a bias-free 1x1 convolution. Args: @@ -123,27 +153,18 @@ def __init__(self, channels: int) -> None: Args: channels: Number of input feature channels. """ - super().__init__() - self.model = nn.Sequential(nn.Dropout(), nn.Conv2d(channels, 1, 1, bias=False)) - - def forward(self, input: torch.Tensor) -> torch.Tensor: - """Compute the calibrated spatial difference map. - - Args: - input: Squared normalized feature differences of shape ``(B, C, H, W)``. - - Returns: - Calibrated difference map of shape ``(B, 1, H, W)``. - """ - return self.model(input) + # The named child retains the model.1.weight keys in upstream calibration files + # and saved PerceptualLoss checkpoints while Sequential supplies forward(). + super().__init__(OrderedDict(model=nn.Sequential(nn.Dropout(), nn.Conv2d(channels, 1, 1, bias=False)))) class LPIPS(nn.Module): - """Internal LPIPS v0.1 implementation for :class:`monai.losses.PerceptualLoss`. + """LPIPS v0.1 network used by :class:`monai.losses.PerceptualLoss`. ImageNet feature weights come from Torchvision. ``pretrained`` controls only the learned linear calibration, matching the original LPIPS constructor. The v0.1 - calibration weights and their license are distributed in the adjacent weights directory. + calibration weights are downloaded from the official ``MONAI/checkpoints`` repository + on Hugging Face, verified with SHA-256, and cached in the Torch Hub checkpoints directory. Args: pretrained: Whether to load pretrained linear calibration weights. The feature @@ -152,46 +173,45 @@ class LPIPS(nn.Module): Raises: ValueError: If ``net`` is not a supported feature backbone name. + monai.apps.HashCheckError: If the calibration checkpoint fails integrity verification. + RuntimeError: If downloading the calibration checkpoint fails. + OSError: If the calibration checkpoint cannot be downloaded or read. """ def __init__(self, pretrained: bool = True, net: str = "alex") -> None: """Initialize the ImageNet feature backbone and LPIPS calibration layers. Args: - pretrained: Whether to load the bundled linear calibration weights. + pretrained: Whether to download and load pretrained linear calibration weights. This does not change the ImageNet weights used by the feature backbone. net: Feature backbone name: ``"alex"``, ``"vgg"``, or ``"squeeze"``. Raises: ValueError: If ``net`` is not a supported feature backbone name. + monai.apps.HashCheckError: If the calibration checkpoint fails integrity verification. + RuntimeError: If downloading the calibration checkpoint fails. + OSError: If the calibration checkpoint cannot be downloaded or read. """ super().__init__() - networks = { - "alex": ("alexnet", "AlexNet_Weights", (2, 5, 8, 10, 12), (64, 192, 384, 256, 256)), - "vgg": ("vgg16", "VGG16_Weights", (4, 9, 16, 23, 30), (64, 128, 256, 512, 512)), - "squeeze": ( - "squeezenet1_1", - "SqueezeNet1_1_Weights", - (2, 5, 8, 10, 11, 12, 13), - (64, 128, 256, 384, 384, 512, 512), - ), - } - if net not in networks: + if net not in LPIPS_NETWORKS: raise ValueError(f"Unsupported LPIPS network: {net}.") - factory, weights, endpoints, channels = networks[net] - self.scaling_layer = _ScalingLayer() + factory, weights, endpoints, channels, hash_val = LPIPS_NETWORKS[net] + self.scaling_layer = ScalingLayer() backbone = getattr(torchvision.models, factory)(weights=getattr(torchvision.models, weights).IMAGENET1K_V1) - self.net = _LPIPSFeatures(backbone.features, endpoints) + self.net = LPIPSFeatures(backbone.features, endpoints) # Legacy checkpoints contain both lin{index} and lins.{index} keys, so register # each calibration layer under both names while sharing the same parameters. layers = [] for index, channel_count in enumerate(channels): - layer = _NetLinLayer(channel_count) + layer = NetLinLayer(channel_count) self.add_module(f"lin{index}", layer) layers.append(layer) self.lins = nn.ModuleList(layers) if pretrained: - path = Path(__file__).with_name("weights") / f"{net}.pth" + path = Path(torch.hub.get_dir()) / "checkpoints" / f"lpips_v0.1_{net}.pth" + download_url( + f"{LPIPS_WEIGHTS_URL}/{net}.pth", filepath=path, hash_val=hash_val, hash_type="sha256", progress=False + ) self.load_state_dict(torch.load(path, map_location="cpu", weights_only=True), strict=False) self.eval() diff --git a/pyproject.toml b/pyproject.toml index 16025ea6b36..cad862b942f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,7 @@ description = "AI Toolkit for Healthcare Imaging" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.10" license = "Apache-2.0" -license-files = ["LICENSE", "monai/losses/weights/LICENSE.LPIPS"] +license-files = ["LICENSE", "monai/networks/nets/LICENSE.LPIPS"] authors = [{ name = "MONAI Consortium", email = "monai.contact@gmail.com" }] classifiers = [ "Intended Audience :: Developers", diff --git a/setup.py b/setup.py index aa3aeea8394..73ff3460341 100644 --- a/setup.py +++ b/setup.py @@ -165,6 +165,6 @@ def get_cmds(): cmdclass=get_cmds(), packages=find_packages(exclude=("docs", "examples", "tests", "tests.*")), zip_safe=False, - package_data=cast(Any, {"monai": ["py.typed", "losses/weights/*", *jit_extension_source]}), + package_data=cast(Any, {"monai": ["py.typed", *jit_extension_source]}), ext_modules=get_extensions(), ) diff --git a/tests/losses/test_perceptual_lpips.py b/tests/losses/test_perceptual_lpips.py index 9a4d805ff91..303b5aa6ea0 100644 --- a/tests/losses/test_perceptual_lpips.py +++ b/tests/losses/test_perceptual_lpips.py @@ -13,6 +13,7 @@ import json import unittest +from contextlib import ExitStack from pathlib import Path from unittest.mock import patch @@ -20,8 +21,9 @@ from parameterized import parameterized from monai.losses import PerceptualLoss -from monai.losses._perceptual import LPIPS +from monai.networks.nets import LPIPS from monai.utils import optional_import +from tests.lpips_test_utils import lpips_test_cache from tests.test_utils import skip_if_quick torchvision, has_torchvision = optional_import("torchvision") @@ -39,6 +41,12 @@ def test_unsupported_network(self): @unittest.skipUnless(has_torchvision, "Requires torchvision") @skip_if_quick class TestPerceptualLPIPS(unittest.TestCase): + def setUp(self): + """Use local calibration fixtures without replacing cache/hash/load logic.""" + stack = ExitStack() + self.addCleanup(stack.close) + _, self.calibrations, _ = stack.enter_context(lpips_test_cache()) + @parameterized.expand( [ (net, factory, weights, pretrained) @@ -64,8 +72,7 @@ def test_distance_and_gradient_without_lpips(self, net, factory_name, weights_na self.assertFalse(model.training) self.assertTrue(all(not p.requires_grad for p in model.net.parameters())) self.assertTrue(all(p.requires_grad for p in model.lins.parameters())) - calibration_path = Path(__file__).parents[2] / "monai" / "losses" / "weights" / f"{net}.pth" - calibrated_state = torch.load(calibration_path, map_location="cpu", weights_only=True) + calibrated_state = self.calibrations[net] for key, value in calibrated_state.items(): self.assertEqual(torch.equal(model.state_dict()[key], value), pretrained) for channels in (1, 3): diff --git a/tests/lpips_test_utils.py b/tests/lpips_test_utils.py new file mode 100644 index 00000000000..ef0f505afb2 --- /dev/null +++ b/tests/lpips_test_utils.py @@ -0,0 +1,77 @@ +# Copyright (c) MONAI Consortium +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import annotations + +import hashlib +import shutil +from contextlib import contextmanager +from pathlib import Path +from tempfile import TemporaryDirectory +from unittest.mock import patch +from urllib.parse import urlparse + +import torch + +from monai.networks.nets.perceptual import LPIPS_NETWORKS + + +@contextmanager +def lpips_test_cache(preload: bool = True): + """Provide synthetic calibration files while retaining real cache/hash/load behavior. + + Args: + preload: Whether the checkpoint cache is initially populated. + + Yields: + The cache directory, expected calibration tensors and mocked network transport. + """ + channels = { + "alex": (64, 192, 384, 256, 256), + "vgg": (64, 128, 256, 512, 512), + "squeeze": (64, 128, 256, 384, 384, 512, 512), + } + with TemporaryDirectory() as directory: + root = Path(directory) + cache = root / "hub" + expected = {} + sources = {} + metadata = {} + for net, sizes in channels.items(): + expected[net] = { + f"lin{i}.model.1.weight": torch.full((1, size, 1, 1), 0.125) for i, size in enumerate(sizes) + } + sources[net] = root / f"{net}.pth" + torch.save(expected[net], sources[net]) + digest = hashlib.sha256(sources[net].read_bytes()).hexdigest() + metadata[net] = (*LPIPS_NETWORKS[net][:-1], digest) + if preload: + destination = cache / "checkpoints" / f"lpips_v0.1_{net}.pth" + destination.parent.mkdir(parents=True, exist_ok=True) + shutil.copyfile(sources[net], destination) + + def fetch(url, filepath, progress): + """Copy a synthetic source in place of the external HTTP transfer. + + Args: + url: Official checkpoint URL identifying the network. + filepath: Temporary destination supplied by download_url. + progress: Requested progress display, unused for the local copy. + """ + net = Path(urlparse(url).path).stem + shutil.copyfile(sources[net], filepath) + + with ( + patch.dict(LPIPS_NETWORKS, metadata), + patch("torch.hub.get_dir", return_value=str(cache)), + patch("monai.apps.utils._download_with_progress", side_effect=fetch) as transfer, + ): + yield cache, expected, transfer diff --git a/tests/min_tests.py b/tests/min_tests.py index 0dcbe498169..a7ec441341a 100644 --- a/tests/min_tests.py +++ b/tests/min_tests.py @@ -214,6 +214,7 @@ def run_testsuit(): "test_bundle_workflow", "test_zarr_avg_merger", "test_perceptual_loss", + "test_perceptual", "test_perceptual_lpips", "test_ultrasound_confidence_map_transform", "test_vista3d_utils", diff --git a/tests/networks/nets/test_perceptual.py b/tests/networks/nets/test_perceptual.py new file mode 100644 index 00000000000..4c22ccf5654 --- /dev/null +++ b/tests/networks/nets/test_perceptual.py @@ -0,0 +1,131 @@ +# Copyright (c) MONAI Consortium +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +from __future__ import annotations + +import unittest +from contextlib import ExitStack +from pathlib import Path +from unittest.mock import patch +from urllib.error import URLError + +import torch +from torch import nn + +from monai.apps import HashCheckError +from monai.networks.nets import LPIPS, LPIPSFeatures, NetLinLayer, ScalingLayer +from monai.utils import optional_import +from tests.lpips_test_utils import lpips_test_cache + +torchvision, has_torchvision = optional_import("torchvision") + + +class TestLPIPSHelpers(unittest.TestCase): + """Check public helpers and the sequential feature data flow.""" + + def test_feature_slices_are_chained(self): + """Later slices must consume preceding features rather than the RGB input.""" + first = nn.Conv2d(3, 4, 1, bias=False) + second = nn.Conv2d(4, 5, 1, bias=False) + with torch.no_grad(): + first.weight.fill_(1.0) + second.weight.fill_(0.5) + model = LPIPSFeatures(nn.Sequential(first, nn.ReLU(), second), (2, 3)) + self.assertIsInstance(model, nn.Sequential) + outputs = model(torch.ones(1, 3, 2, 2)) + torch.testing.assert_close(outputs[0], torch.full((1, 4, 2, 2), 3.0)) + torch.testing.assert_close(outputs[1], torch.full((1, 5, 2, 2), 6.0)) + self.assertTrue(all(not p.requires_grad for p in model.parameters())) + + def test_sequential_calibration_preserves_checkpoint_key(self): + """The Sequential implementation retains upstream model.1.weight keys.""" + model = NetLinLayer(3).eval() + self.assertIsInstance(model, nn.Sequential) + with torch.no_grad(): + model.model[1].weight.fill_(1.0) + torch.testing.assert_close(model(torch.ones(1, 3, 2, 2)), torch.full((1, 1, 2, 2), 3.0)) + self.assertEqual(set(model.state_dict()), {"model.1.weight"}) + + def test_grayscale_scaling(self): + """Grayscale input uses the original three channel scaling constants.""" + output = ScalingLayer()(torch.zeros(1, 1, 2, 2)) + expected = torch.tensor([0.0655021834, 0.1964285714, 0.4177777778]).view(1, 3, 1, 1) + torch.testing.assert_close(output, expected.expand(1, 3, 2, 2)) + + +@unittest.skipUnless(has_torchvision, "Requires torchvision") +class TestLPIPSDownloads(unittest.TestCase): + """Exercise real download, integrity and cache logic with a local transport.""" + + def setUp(self): + """Isolate the cache and replace only ImageNet and HTTP downloads.""" + stack = ExitStack() + self.addCleanup(stack.close) + self.cache, self.expected, self.transfer = stack.enter_context(lpips_test_cache(preload=False)) + factory = torchvision.models.squeezenet1_1 + stack.enter_context( + patch.object(torchvision.models, "squeezenet1_1", side_effect=lambda **kwargs: factory(weights=None)) + ) + self.checkpoint = self.cache / "checkpoints" / "lpips_v0.1_squeeze.pth" + + def assert_calibration_loaded(self, model): + """Check every calibrated layer against the independent fixture tensors. + + Args: + model: LPIPS network whose pretrained calibration has been loaded. + """ + for key, value in self.expected["squeeze"].items(): + torch.testing.assert_close(model.state_dict()[key], value, rtol=0, atol=0) + + def test_download_and_offline_cache_reuse(self): + """A cold cache downloads once; a warm cache loads without HTTP access.""" + self.assert_calibration_loaded(LPIPS(net="squeeze")) + self.assertTrue(self.checkpoint.exists()) + self.transfer.assert_called_once() + self.assertEqual( + self.transfer.call_args.args[0], "https://huggingface.co/MONAI/checkpoints/resolve/main/squeeze.pth" + ) + self.transfer.side_effect = AssertionError("A valid cached checkpoint must not be downloaded again") + self.assert_calibration_loaded(LPIPS(net="squeeze")) + + def test_random_calibration_does_not_download(self): + """pretrained=False leaves calibration random and does not access its URL.""" + self.transfer.side_effect = AssertionError("Random calibration must not download weights") + model = LPIPS(net="squeeze", pretrained=False) + self.assertFalse(self.checkpoint.exists()) + for key, value in self.expected["squeeze"].items(): + self.assertFalse(torch.equal(model.state_dict()[key], value)) + + def test_corrupt_download_is_rejected(self): + """Failed integrity validation must not silently use random calibration.""" + self.transfer.side_effect = lambda url, filepath, progress: Path(filepath).write_bytes(b"invalid checkpoint") + with self.assertRaises(HashCheckError): + LPIPS(net="squeeze") + self.assertFalse(self.checkpoint.exists()) + + def test_corrupt_cache_is_rejected(self): + """Cached weights are validated before being passed to torch.load.""" + LPIPS(net="squeeze") + self.checkpoint.write_bytes(b"corrupt cache") + self.transfer.side_effect = AssertionError("Corrupt existing cache must be reported") + with self.assertRaises(HashCheckError): + LPIPS(net="squeeze") + + def test_network_failure_is_reported(self): + """An unavailable server must fail instead of returning an uncalibrated model.""" + self.transfer.side_effect = URLError("offline") + with self.assertRaises(URLError): + LPIPS(net="squeeze") + self.assertFalse(self.checkpoint.exists()) + + +if __name__ == "__main__": + unittest.main() From 56c7ec92d69964d510afa1f0f04001659c1f6086 Mon Sep 17 00:00:00 2001 From: oynal Date: Tue, 17 Nov 2026 23:42:19 +0800 Subject: [PATCH 5/5] Simplify LPIPS tests following review Use small checkpoint mocks, preserve dynamic cache selection, and remove redundant license and docstring content. Assisted-by: Codex Signed-off-by: oynal --- docs/source/installation.md | 2 +- monai/networks/nets/LICENSE.LPIPS | 23 ----- monai/networks/nets/perceptual.py | 32 ++----- pyproject.toml | 2 +- tests/losses/test_perceptual_lpips.py | 114 ++++++++--------------- tests/lpips_test_utils.py | 77 ---------------- tests/networks/nets/test_perceptual.py | 122 ++++++++++++------------- 7 files changed, 103 insertions(+), 269 deletions(-) delete mode 100644 monai/networks/nets/LICENSE.LPIPS delete mode 100644 tests/lpips_test_utils.py diff --git a/docs/source/installation.md b/docs/source/installation.md index e02012015a6..cba17548025 100644 --- a/docs/source/installation.md +++ b/docs/source/installation.md @@ -77,7 +77,7 @@ pip install monai MONAI supports the extras syntax such as `pip install 'monai[nibabel]'`. The options are ```text -clearml, cucim, cupy, einops, fire, gdown, h5py, huggingface_hub, hyena, ignite, imagecodecs, itk, jsonschema, lmdb, lpips, matplotlib, metrics_reloaded, mlflow, nibabel, nni, nvimgcodec, onnx, openslide, optuna, pandas, pillow, polygraphy, psutil, pyamg, pybind11, pydicom, pynrrd, pynvml, pyyaml, requests, segment_anything, scipy, skimage, tensorboard, tensorboardX, tifffile, torchio, torchvision, tqdm, transformers, zarr +clearml, cucim, cupy, einops, fire, gdown, h5py, huggingface_hub, hyena, ignite, imagecodecs, itk, jsonschema, lmdb, matplotlib, metrics_reloaded, mlflow, nibabel, nni, nvimgcodec, onnx, openslide, optuna, pandas, pillow, polygraphy, psutil, pyamg, pybind11, pydicom, pynrrd, pynvml, pyyaml, requests, segment_anything, scipy, skimage, tensorboard, tensorboardX, tifffile, torchio, torchvision, tqdm, transformers, zarr ``` which correspond to the packages: `clearml`, `cucim` (`cucim-cu12` or `cucim-cu13`), `cupy-cuda13x`, `einops`, `fire`, `gdown`, `h5py`, `huggingface_hub`, `nvsubquadratic`, `omegaconf`, `pytorch-ignite`, `imagecodecs`, `itk`, `jsonschema`, `lmdb`, `matplotlib`, `MetricsReloaded`, `mlflow`, `nibabel`, `nni`, `filelock`, `nvidia-nvimgcodec-cu13`, `onnx`, `onnxruntime`, `onnx_graphsurgeon`, `onnxscript`, `openslide-python`, `openslide-bin`, `optuna`, `pandas`, `pillow`, `polygraphy`, `psutil`, `pyamg`, `pybind11`, `pydicom`, `pynrrd`, `nvidia-ml-py`, `pyyaml`, `requests`, `segment_anything`, `scipy`, `scikit-image`, `tensorboard`, `tensorboardX`, `tifffile`, `torchio`, `torchvision`, `tqdm`, `transformers`, `zarr`. diff --git a/monai/networks/nets/LICENSE.LPIPS b/monai/networks/nets/LICENSE.LPIPS deleted file mode 100644 index 842c363a7fc..00000000000 --- a/monai/networks/nets/LICENSE.LPIPS +++ /dev/null @@ -1,23 +0,0 @@ -Copyright (c) 2018, Richard Zhang, Phillip Isola, Alexei A. Efros, Eli Shechtman, Oliver Wang -All rights reserved. - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are met: - -* Redistributions of source code must retain the above copyright notice, this - list of conditions and the following disclaimer. - -* Redistributions in binary form must reproduce the above copyright notice, - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - -THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" -AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE -FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER -CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, -OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/monai/networks/nets/perceptual.py b/monai/networks/nets/perceptual.py index e7b611f2a38..aedf8d3fc2d 100644 --- a/monai/networks/nets/perceptual.py +++ b/monai/networks/nets/perceptual.py @@ -49,6 +49,8 @@ __all__ = ["LPIPS", "LPIPSFeatures", "NetLinLayer", "ScalingLayer"] +# Resolve the default at construction time so torch.hub.set_dir() remains effective. +LPIPS_CHECKPOINTS_DIR: Path | None = None LPIPS_WEIGHTS_URL = "https://huggingface.co/MONAI/checkpoints/resolve/main" LPIPS_NETWORKS = { "alex": ( @@ -79,7 +81,6 @@ class ScalingLayer(nn.Module): """Apply the fixed RGB shift and scale used by LPIPS v0.1.""" def __init__(self) -> None: - """Register the channel-wise shift and scale as buffers.""" super().__init__() self.register_buffer("shift", torch.tensor([-0.030, -0.088, -0.188])[None, :, None, None]) self.register_buffer("scale", torch.tensor([0.458, 0.448, 0.450])[None, :, None, None]) @@ -105,12 +106,6 @@ class LPIPSFeatures(nn.Sequential): """ def __init__(self, features: nn.Sequential, endpoints: tuple[int, ...]) -> None: - """Build successive feature slices and freeze their parameters. - - Args: - features: Ordered feature layers from a Torchvision backbone. - endpoints: Exclusive layer indices at which each successive slice ends. - """ slices: OrderedDict[str, nn.Module] = OrderedDict() start = 0 for index, end in enumerate(endpoints, 1): @@ -148,11 +143,6 @@ class NetLinLayer(nn.Sequential): """ def __init__(self, channels: int) -> None: - """Initialize a calibration layer. - - Args: - channels: Number of input feature channels. - """ # The named child retains the model.1.weight keys in upstream calibration files # and saved PerceptualLoss checkpoints while Sequential supplies forward(). super().__init__(OrderedDict(model=nn.Sequential(nn.Dropout(), nn.Conv2d(channels, 1, 1, bias=False)))) @@ -179,19 +169,6 @@ class LPIPS(nn.Module): """ def __init__(self, pretrained: bool = True, net: str = "alex") -> None: - """Initialize the ImageNet feature backbone and LPIPS calibration layers. - - Args: - pretrained: Whether to download and load pretrained linear calibration weights. - This does not change the ImageNet weights used by the feature backbone. - net: Feature backbone name: ``"alex"``, ``"vgg"``, or ``"squeeze"``. - - Raises: - ValueError: If ``net`` is not a supported feature backbone name. - monai.apps.HashCheckError: If the calibration checkpoint fails integrity verification. - RuntimeError: If downloading the calibration checkpoint fails. - OSError: If the calibration checkpoint cannot be downloaded or read. - """ super().__init__() if net not in LPIPS_NETWORKS: raise ValueError(f"Unsupported LPIPS network: {net}.") @@ -208,7 +185,10 @@ def __init__(self, pretrained: bool = True, net: str = "alex") -> None: layers.append(layer) self.lins = nn.ModuleList(layers) if pretrained: - path = Path(torch.hub.get_dir()) / "checkpoints" / f"lpips_v0.1_{net}.pth" + directory = ( + LPIPS_CHECKPOINTS_DIR if LPIPS_CHECKPOINTS_DIR is not None else Path(torch.hub.get_dir(), "checkpoints") + ) + path = directory / f"lpips_v0.1_{net}.pth" download_url( f"{LPIPS_WEIGHTS_URL}/{net}.pth", filepath=path, hash_val=hash_val, hash_type="sha256", progress=False ) diff --git a/pyproject.toml b/pyproject.toml index cad862b942f..01d5aee18b7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,7 +19,7 @@ description = "AI Toolkit for Healthcare Imaging" readme = { file = "README.md", content-type = "text/markdown" } requires-python = ">=3.10" license = "Apache-2.0" -license-files = ["LICENSE", "monai/networks/nets/LICENSE.LPIPS"] +license-files = ["LICENSE"] authors = [{ name = "MONAI Consortium", email = "monai.contact@gmail.com" }] classifiers = [ "Intended Audience :: Developers", diff --git a/tests/losses/test_perceptual_lpips.py b/tests/losses/test_perceptual_lpips.py index 303b5aa6ea0..660764ff2cf 100644 --- a/tests/losses/test_perceptual_lpips.py +++ b/tests/losses/test_perceptual_lpips.py @@ -13,7 +13,6 @@ import json import unittest -from contextlib import ExitStack from pathlib import Path from unittest.mock import patch @@ -23,17 +22,17 @@ from monai.losses import PerceptualLoss from monai.networks.nets import LPIPS from monai.utils import optional_import -from tests.lpips_test_utils import lpips_test_cache -from tests.test_utils import skip_if_quick +from tests.test_utils import dict_product, skip_if_quick torchvision, has_torchvision = optional_import("torchvision") -class TestPerceptualLPIPSValidation(unittest.TestCase): - """Check argument validation before any optional backbone is constructed.""" +TEST_NETWORKS = [("alex", "alexnet"), ("vgg", "vgg16"), ("squeeze", "squeezenet1_1")] +TEST_INPUTS = [(params,) for params in dict_product(network=TEST_NETWORKS, channels=[1, 3])] + +class TestPerceptualLPIPSValidation(unittest.TestCase): def test_unsupported_network(self): - """Reject unsupported names before constructing a Torchvision backbone.""" with self.assertRaisesRegex(ValueError, "Unsupported LPIPS network"): LPIPS(net="unsupported") @@ -42,84 +41,49 @@ def test_unsupported_network(self): @skip_if_quick class TestPerceptualLPIPS(unittest.TestCase): def setUp(self): - """Use local calibration fixtures without replacing cache/hash/load logic.""" - stack = ExitStack() - self.addCleanup(stack.close) - _, self.calibrations, _ = stack.enter_context(lpips_test_cache()) - - @parameterized.expand( - [ - (net, factory, weights, pretrained) - for net, factory, weights in ( - ("alex", "alexnet", "AlexNet_Weights"), - ("vgg", "vgg16", "VGG16_Weights"), - ("squeeze", "squeezenet1_1", "SqueezeNet1_1_Weights"), - ) - for pretrained in (True, False) - ] - ) - def test_distance_and_gradient_without_lpips(self, net, factory_name, weights_name, pretrained): - # Only replace external weight downloading; use the actual Torchvision networks. - factory = getattr(torchvision.models, factory_name) + # Use real feature networks, replacing only external ImageNet downloads. torch.manual_seed(9284) - with patch.object( - torchvision.models, factory_name, side_effect=lambda **kwargs: factory(weights=None) - ) as create_backbone: - loss = PerceptualLoss(spatial_dims=2, network_type=net, pretrained=pretrained) - create_backbone.assert_called_once_with(weights=getattr(torchvision.models, weights_name).IMAGENET1K_V1) - - model = loss.perceptual_function - self.assertFalse(model.training) - self.assertTrue(all(not p.requires_grad for p in model.net.parameters())) - self.assertTrue(all(p.requires_grad for p in model.lins.parameters())) - calibrated_state = self.calibrations[net] - for key, value in calibrated_state.items(): - self.assertEqual(torch.equal(model.state_dict()[key], value), pretrained) - for channels in (1, 3): - with self.subTest(channels=channels): - source = torch.rand(2, channels, 64, 64, requires_grad=True) - target = torch.rand_like(source) - self.assertEqual(loss(source, source).item(), 0.0) - distance = model(source, target) - self.assertEqual(distance.shape, (2, 1, 1, 1)) - self.assertTrue(torch.isfinite(distance).all()) - if pretrained: - self.assertTrue(torch.all(distance > 0)) - else: - # Random calibration layers need not define a nonnegative metric. - self.assertTrue(torch.all(distance != 0)) - torch.testing.assert_close(distance, model(target, source)) - torch.testing.assert_close(loss(source, target), distance.mean()) - distance.mean().backward() - self.assertTrue(torch.isfinite(source.grad).all()) - self.assertGreater(source.grad.abs().sum().item(), 0) - - # Existing checkpoints contain both names for the same registered calibration layers. - state = model.state_dict() - self.assertIn("net.slice1.0.weight", state) - torch.testing.assert_close(state["lin0.model.1.weight"], state["lins.0.model.1.weight"]) - self.assertTrue(all(torch.isfinite(value).all() for value in state.values())) - - @parameterized.expand([("alex", "alexnet"), ("vgg", "vgg16"), ("squeeze", "squeezenet1_1")]) + for _, factory_name in TEST_NETWORKS: + factory = getattr(torchvision.models, factory_name) + patcher = patch.object( + torchvision.models, factory_name, side_effect=lambda factory=factory, **kwargs: factory(weights=None) + ) + self.addCleanup(patcher.stop) + patcher.start() + + @parameterized.expand(TEST_INPUTS) + def test_distance(self, params): + loss = PerceptualLoss(spatial_dims=2, network_type=params["network"][0], pretrained=False) + source = torch.rand(2, params["channels"], 64, 64) + target = torch.rand_like(source) + distance = loss.perceptual_function(source, target) + self.assertEqual(distance.shape, (2, 1, 1, 1)) + self.assertTrue(torch.isfinite(distance).all()) + self.assertEqual(loss(source, source).item(), 0.0) + torch.testing.assert_close(distance, loss.perceptual_function(target, source)) + torch.testing.assert_close(loss(source, target), distance.mean()) + + @parameterized.expand(TEST_INPUTS) + def test_input_gradient(self, params): + loss = PerceptualLoss(spatial_dims=2, network_type=params["network"][0], pretrained=False) + source = torch.rand(2, params["channels"], 64, 64, requires_grad=True) + loss(source, torch.rand_like(source)).backward() + self.assertTrue(torch.isfinite(source.grad).all()) + self.assertGreater(source.grad.abs().sum().item(), 0) + + @parameterized.expand(TEST_NETWORKS) def test_load_legacy_state_dict(self, net, factory_name): - # Captured from unmodified LPIPS v0.1, independent of MONAI's module registration. + # Independent key/shape manifest captured from unmodified LPIPS v0.1. manifest_path = Path(__file__).parents[1] / "testing_data" / "lpips_v0_1_state_dict.json" manifest = json.loads(manifest_path.read_text())["networks"][net] - factory = getattr(torchvision.models, factory_name) - with patch.object(torchvision.models, factory_name, side_effect=lambda **kwargs: factory(weights=None)): - loss = PerceptualLoss(spatial_dims=2, network_type=net) + loss = PerceptualLoss(spatial_dims=2, network_type=net, pretrained=False) legacy_state = {f"perceptual_function.{key}": torch.full(shape, 0.125) for key, shape in manifest.items()} loss.load_state_dict(legacy_state, strict=True) - self.assertEqual(set(loss.state_dict()), set(legacy_state)) for key, value in loss.state_dict().items(): - with self.subTest(key=key): - self.assertEqual(tuple(value.shape), tuple(manifest[key.removeprefix("perceptual_function.")])) - torch.testing.assert_close(value, legacy_state[key], rtol=0, atol=0) + torch.testing.assert_close(value, legacy_state[key], rtol=0, atol=0) def test_fake_3d_matches_three_axes(self): - factory = torchvision.models.squeezenet1_1 - with patch.object(torchvision.models, "squeezenet1_1", side_effect=lambda **kwargs: factory(weights=None)): - loss = PerceptualLoss(spatial_dims=3, network_type="squeeze", fake_3d_ratio=1.0) + loss = PerceptualLoss(spatial_dims=3, network_type="squeeze", fake_3d_ratio=1.0, pretrained=False) source = torch.rand(1, 1, 32, 32, 32, requires_grad=True) target = torch.rand_like(source) expected = sum( diff --git a/tests/lpips_test_utils.py b/tests/lpips_test_utils.py deleted file mode 100644 index ef0f505afb2..00000000000 --- a/tests/lpips_test_utils.py +++ /dev/null @@ -1,77 +0,0 @@ -# Copyright (c) MONAI Consortium -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# http://www.apache.org/licenses/LICENSE-2.0 -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -from __future__ import annotations - -import hashlib -import shutil -from contextlib import contextmanager -from pathlib import Path -from tempfile import TemporaryDirectory -from unittest.mock import patch -from urllib.parse import urlparse - -import torch - -from monai.networks.nets.perceptual import LPIPS_NETWORKS - - -@contextmanager -def lpips_test_cache(preload: bool = True): - """Provide synthetic calibration files while retaining real cache/hash/load behavior. - - Args: - preload: Whether the checkpoint cache is initially populated. - - Yields: - The cache directory, expected calibration tensors and mocked network transport. - """ - channels = { - "alex": (64, 192, 384, 256, 256), - "vgg": (64, 128, 256, 512, 512), - "squeeze": (64, 128, 256, 384, 384, 512, 512), - } - with TemporaryDirectory() as directory: - root = Path(directory) - cache = root / "hub" - expected = {} - sources = {} - metadata = {} - for net, sizes in channels.items(): - expected[net] = { - f"lin{i}.model.1.weight": torch.full((1, size, 1, 1), 0.125) for i, size in enumerate(sizes) - } - sources[net] = root / f"{net}.pth" - torch.save(expected[net], sources[net]) - digest = hashlib.sha256(sources[net].read_bytes()).hexdigest() - metadata[net] = (*LPIPS_NETWORKS[net][:-1], digest) - if preload: - destination = cache / "checkpoints" / f"lpips_v0.1_{net}.pth" - destination.parent.mkdir(parents=True, exist_ok=True) - shutil.copyfile(sources[net], destination) - - def fetch(url, filepath, progress): - """Copy a synthetic source in place of the external HTTP transfer. - - Args: - url: Official checkpoint URL identifying the network. - filepath: Temporary destination supplied by download_url. - progress: Requested progress display, unused for the local copy. - """ - net = Path(urlparse(url).path).stem - shutil.copyfile(sources[net], filepath) - - with ( - patch.dict(LPIPS_NETWORKS, metadata), - patch("torch.hub.get_dir", return_value=str(cache)), - patch("monai.apps.utils._download_with_progress", side_effect=fetch) as transfer, - ): - yield cache, expected, transfer diff --git a/tests/networks/nets/test_perceptual.py b/tests/networks/nets/test_perceptual.py index 4c22ccf5654..508fb5d1fe2 100644 --- a/tests/networks/nets/test_perceptual.py +++ b/tests/networks/nets/test_perceptual.py @@ -12,22 +12,26 @@ from __future__ import annotations import unittest -from contextlib import ExitStack from pathlib import Path +from tempfile import TemporaryDirectory from unittest.mock import patch -from urllib.error import URLError import torch +from parameterized import parameterized from torch import nn -from monai.apps import HashCheckError +from monai.losses import PerceptualLoss from monai.networks.nets import LPIPS, LPIPSFeatures, NetLinLayer, ScalingLayer from monai.utils import optional_import -from tests.lpips_test_utils import lpips_test_cache +from tests.test_utils import dict_product, skip_if_quick torchvision, has_torchvision = optional_import("torchvision") +TEST_NETWORKS = [("alex", "alexnet"), ("vgg", "vgg16"), ("squeeze", "squeezenet1_1")] +TEST_PRETRAINED = [(params,) for params in dict_product(network=TEST_NETWORKS, pretrained=[True, False])] + + class TestLPIPSHelpers(unittest.TestCase): """Check public helpers and the sequential feature data flow.""" @@ -62,69 +66,55 @@ def test_grayscale_scaling(self): @unittest.skipUnless(has_torchvision, "Requires torchvision") -class TestLPIPSDownloads(unittest.TestCase): - """Exercise real download, integrity and cache logic with a local transport.""" - - def setUp(self): - """Isolate the cache and replace only ImageNet and HTTP downloads.""" - stack = ExitStack() - self.addCleanup(stack.close) - self.cache, self.expected, self.transfer = stack.enter_context(lpips_test_cache(preload=False)) +@skip_if_quick +class TestLPIPSPretrained(unittest.TestCase): + @parameterized.expand(TEST_PRETRAINED) + def test_calibration_checkpoint(self, params): + net, factory_name = params["network"] + factory = getattr(torchvision.models, factory_name) + expected = {"lin0.model.1.weight": torch.full((1, 64, 1, 1), 0.125)} + with TemporaryDirectory() as directory: + checkpoint = Path(directory) / f"lpips_v0.1_{net}.pth" + + def save_checkpoint(url, filepath, **kwargs): + self.assertEqual(filepath, checkpoint) + torch.save(expected, filepath) + + with ( + patch("monai.networks.nets.perceptual.LPIPS_CHECKPOINTS_DIR", Path(directory)), + patch("monai.networks.nets.perceptual.download_url", side_effect=save_checkpoint), + patch.object(torchvision.models, factory_name, side_effect=lambda **kwargs: factory(weights=None)), + ): + model = LPIPS(net=net, pretrained=params["pretrained"]) + self.assertEqual(checkpoint.is_file(), params["pretrained"]) + self.assertEqual( + torch.equal(model.state_dict()["lin0.model.1.weight"], expected["lin0.model.1.weight"]), + params["pretrained"], + ) + + def test_perceptual_loss_cache_dir(self): factory = torchvision.models.squeezenet1_1 - stack.enter_context( - patch.object(torchvision.models, "squeezenet1_1", side_effect=lambda **kwargs: factory(weights=None)) - ) - self.checkpoint = self.cache / "checkpoints" / "lpips_v0.1_squeeze.pth" - - def assert_calibration_loaded(self, model): - """Check every calibrated layer against the independent fixture tensors. - - Args: - model: LPIPS network whose pretrained calibration has been loaded. - """ - for key, value in self.expected["squeeze"].items(): - torch.testing.assert_close(model.state_dict()[key], value, rtol=0, atol=0) - - def test_download_and_offline_cache_reuse(self): - """A cold cache downloads once; a warm cache loads without HTTP access.""" - self.assert_calibration_loaded(LPIPS(net="squeeze")) - self.assertTrue(self.checkpoint.exists()) - self.transfer.assert_called_once() - self.assertEqual( - self.transfer.call_args.args[0], "https://huggingface.co/MONAI/checkpoints/resolve/main/squeeze.pth" - ) - self.transfer.side_effect = AssertionError("A valid cached checkpoint must not be downloaded again") - self.assert_calibration_loaded(LPIPS(net="squeeze")) - - def test_random_calibration_does_not_download(self): - """pretrained=False leaves calibration random and does not access its URL.""" - self.transfer.side_effect = AssertionError("Random calibration must not download weights") - model = LPIPS(net="squeeze", pretrained=False) - self.assertFalse(self.checkpoint.exists()) - for key, value in self.expected["squeeze"].items(): - self.assertFalse(torch.equal(model.state_dict()[key], value)) - - def test_corrupt_download_is_rejected(self): - """Failed integrity validation must not silently use random calibration.""" - self.transfer.side_effect = lambda url, filepath, progress: Path(filepath).write_bytes(b"invalid checkpoint") - with self.assertRaises(HashCheckError): - LPIPS(net="squeeze") - self.assertFalse(self.checkpoint.exists()) - - def test_corrupt_cache_is_rejected(self): - """Cached weights are validated before being passed to torch.load.""" - LPIPS(net="squeeze") - self.checkpoint.write_bytes(b"corrupt cache") - self.transfer.side_effect = AssertionError("Corrupt existing cache must be reported") - with self.assertRaises(HashCheckError): - LPIPS(net="squeeze") - - def test_network_failure_is_reported(self): - """An unavailable server must fail instead of returning an uncalibrated model.""" - self.transfer.side_effect = URLError("offline") - with self.assertRaises(URLError): - LPIPS(net="squeeze") - self.assertFalse(self.checkpoint.exists()) + previous_cache = torch.hub.get_dir() + self.addCleanup(torch.hub.set_dir, previous_cache) + expected = {"lin0.model.1.weight": torch.full((1, 64, 1, 1), 0.125)} + with TemporaryDirectory() as directory: + checkpoint = Path(directory, "checkpoints", "lpips_v0.1_squeeze.pth") + + def save_checkpoint(url, filepath, **kwargs): + self.assertEqual(filepath, checkpoint) + filepath.parent.mkdir(parents=True, exist_ok=True) + torch.save(expected, filepath) + + with ( + patch("monai.networks.nets.perceptual.download_url", side_effect=save_checkpoint), + patch.object(torchvision.models, "squeezenet1_1", side_effect=lambda **kwargs: factory(weights=None)), + self.assertWarnsRegex(UserWarning, "Setting cache_dir"), + ): + loss = PerceptualLoss(spatial_dims=2, network_type="squeeze", cache_dir=directory) + self.assertTrue(checkpoint.is_file()) + torch.testing.assert_close( + loss.perceptual_function.state_dict()["lin0.model.1.weight"], expected["lin0.model.1.weight"] + ) if __name__ == "__main__":