### Install LPIPS Library

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Install the LPIPS library using pip. Alternatively, clone the repository and install from source using requirements.txt.

```bash
pip install lpips
# or from source:
pip install -r requirements.txt
git clone https://github.com/richzhang/PerceptualSimilarity
```

--------------------------------

### Install Dependencies (Bash)

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Install required Python packages from the requirements.txt file. Ensure PyTorch 1.0+ and torchvision are installed.

```bash
pip install -r requirements.txt
```

--------------------------------

### Train and Test Perceptual Metric

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Example script for training and testing the perceptual metric. This script trains a model on the full training set for 10 epochs and then tests it on all validation sets.

```bash
bash train_test_metric.sh
```

--------------------------------

### Forward Pass with LPIPS (Python)

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Perform a forward pass using the LPIPS metric to get the distance between two image tensors. The input tensors should have shape Nx3xHxW and be normalized to [-1,1].

```python
import lpips
loss_fn = lpips.LPIPS(net='alex')
d = loss_fn.forward(im0,im1)
```

--------------------------------

### Train Perceptual Metric from Scratch

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Script to train the perceptual metric from scratch.

```bash
train_test_metric_scratch.sh
```

--------------------------------

### Initialize LPIPS Loss Functions (Python)

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Instantiate LPIPS loss functions for 'alex' (best forward scores) and 'vgg' (closer to traditional perceptual loss for optimization). Requires PyTorch.

```python
import lpips
loss_fn_alex = lpips.LPIPS(net='alex') # best forward scores
loss_fn_vgg = lpips.LPIPS(net='vgg') # closer to "traditional" perceptual loss, when used for optimization
```

--------------------------------

### Clone Repository (Bash)

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Clone the PerceptualSimilarity repository and navigate into the directory. This is necessary for running local scripts.

```bash
git clone https://github.com/richzhang/PerceptualSimilarity
cd PerceptualSimilarity
```

--------------------------------

### Backpropping through LPIPS (Python)

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Demonstrates how to use the LPIPS metric for backpropagation, enabling iterative optimization. This can also be used to implement vanilla VGG loss.

```python
import lpips
loss_fn = lpips.LPIPS(net='vgg') # Use vgg for backprop
# ... optimization loop using loss_fn ...
```

--------------------------------

### Instantiate and Use LPIPS Model

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Instantiate the LPIPS model with different network backbones and versions. Images must be RGB tensors of shape (N, 3, H, W) normalized to [-1, 1]. Use normalize=True to accept [0, 1] input.

```python
import torch
import lpips

# --- Instantiation options ---
# net='alex'    → fastest, best forward metric (default)
# net='vgg'     → closer to traditional perceptual loss; preferred for backprop
# net='squeeze' → smallest model (~2.8 MB)
# lpips=True    → use learned linear calibration layers (default)
# lpips=False   → average all feature layers equally (baseline)
# spatial=True  → return a per-pixel distance map instead of a scalar
# version='0.1' → current (default); '0.0' = original buggy release

loss_fn = lpips.LPIPS(net='alex', version='0.1')  # best for evaluation
loss_fn_vgg = lpips.LPIPS(net='vgg')               # best for optimization/loss

# Move to GPU if available
# loss_fn = loss_fn.cuda()

# --- Tensor inputs: shape (N, 3, H, W), range [-1, 1] ---
img0 = torch.rand(4, 3, 128, 128) * 2 - 1   # batch of 4 random images
img1 = torch.rand(4, 3, 128, 128) * 2 - 1

dist = loss_fn(img0, img1)                   # shape: (4, 1, 1, 1)
print(dist.squeeze())
# tensor([0.4821, 0.5103, 0.4977, 0.5012], grad_fn=<SqueezeBackward0>)

# --- normalize=True: accepts [0, 1] input and rescales to [-1, 1] internally ---
img0_01 = torch.rand(1, 3, 64, 64)
img1_01 = torch.rand(1, 3, 64, 64)
dist = loss_fn(img0_01, img1_01, normalize=True)
print('Distance:', dist.item())   # e.g. Distance: 0.5234

# --- Per-layer distances ---
total_dist, per_layer = loss_fn(img0[:1], img1[:1], retPerLayer=True)
print('Total:', total_dist.item())
print('Per layer distances:', [l.item() for l in per_layer])
# Total: 0.4821
# Per layer distances: [0.1102, 0.0983, 0.1241, 0.0876, 0.0619]
```

--------------------------------

### LPIPS Training Wrapper

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Initializes and uses the `lpips.Trainer` for managing model training, including forward/backward passes, optimizer state, and checkpoint saving. Supports training with BAPPS dataset for 2AFC tasks.

```python
import lpips
from data import data_loader as dl

# Initialize trainer in training mode
trainer = lpips.Trainer()
trainer.initialize(
    model='lpips',
    net='alex',
    use_gpu=False,
    is_train=True,
    lr=1e-4,
    beta1=0.5,
    version='0.1',
)

# Load BAPPS 2AFC training data
data_loader = dl.CreateDataLoader(
    ['train/traditional', 'train/cnn'],
    dataset_mode='2afc',
    batch_size=50,
    serial_batches=False,
    nThreads=4,
)

for epoch in range(1, 6):
    for data in data_loader.load_data():
        trainer.set_input(data)
        trainer.optimize_parameters()

    errors = trainer.get_current_errors()
    print('Epoch %d | loss: %.4f | acc: %.4f' % (
        epoch, errors['loss_total'], errors['acc_r']))
    trainer.save('./checkpoints/my_model', epoch)
```

--------------------------------

### Image I/O Utilities: Load, Convert, and Invert

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Use `load_image` to read image files into NumPy arrays, `im2tensor` to convert them to PyTorch tensors normalized to [-1, 1], and `tensor2im` to convert back to displayable NumPy arrays.

```python
import lpips

# Load and convert a single image
img_np  = lpips.load_image('./imgs/ex_ref.png')   # np.ndarray, uint8, (H,W,3)
img_t   = lpips.im2tensor(img_np)                 # torch.Tensor (1,3,H,W) in [-1,1]

```

--------------------------------

### Calculate Distances Between All Pairs in a Directory (Command Line)

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Use the lpips_1dir_allpairs.py script to compute perceptual distances between all unique pairs of images within a single directory. Results are saved to an output file.

```bash
python lpips_1dir_allpairs.py -d imgs/ex_dir_pair -o imgs/example_dists_pair.txt --use_gpu
```

--------------------------------

### lpips.Trainer

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

A high-level training wrapper that manages model initialization, forward/backward passes, optimizer state, and checkpoint saving. It supports training with human perceptual judgment data from the BAPPS dataset.

```APIDOC
## `lpips.Trainer` – Training wrapper

High-level training wrapper that manages model initialization, forward/backward passes, optimizer state, and checkpoint saving. Supports training with human perceptual judgment data from the BAPPS dataset.

```python
import lpips
from data import data_loader as dl

# Initialize trainer in training mode
trainer = lpips.Trainer()
trainer.initialize(
    model='lpips',      # 'lpips' | 'baseline' | 'L2' | 'SSIM'
    net='alex',         # 'alex' | 'vgg' | 'squeeze'
    use_gpu=False,
    is_train=True,
    lr=1e-4,
    beta1=0.5,
    version='0.1',
)

# Load BAPPS 2AFC training data
data_loader = dl.CreateDataLoader(
    ['train/traditional', 'train/cnn'],
    dataset_mode='2afc',
    batch_size=50,
    serial_batches=False,
    nThreads=4,
)

for epoch in range(1, 6):
    for data in data_loader.load_data():
        trainer.set_input(data)         # expects keys: ref, p0, p1, judge
        trainer.optimize_parameters()   # forward + backward + optimizer step

    errors = trainer.get_current_errors()
    print('Epoch %d | loss: %.4f | acc: %.4f' % (
        epoch, errors['loss_total'], errors['acc_r']))
    trainer.save('./checkpoints/my_model', epoch)
# Epoch 1 | loss: 0.6823 | acc: 0.6241
# Epoch 2 | loss: 0.6501 | acc: 0.6589
```
```

--------------------------------

### lpips.im2tensor / lpips.load_image – Image I/O utilities

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Utilities for reading image files and converting them to PyTorch tensors suitable for the LPIPS model, and vice-versa.

```APIDOC
## Image I/O Utilities

### Description
Provides functions to load images from files and convert them between NumPy arrays and PyTorch tensors.

### Functions
*   **lpips.load_image(path)**: Reads an image file (PNG, JPG, BMP, DNG) into a `uint8` NumPy array (H, W, 3).
*   **lpips.im2tensor(img_np)**: Converts a NumPy array image (H, W, 3) to a PyTorch tensor of shape (1, 3, H, W) normalized to `[-1, 1]`.
*   **lpips.tensor2im(img_t)**: Converts a PyTorch tensor image back to a `uint8` NumPy array.

### Request Example
```python
import lpips

# Load and convert a single image
img_np  = lpips.load_image('./imgs/ex_ref.png')   # np.ndarray, uint8, (H,W,3)
img_t   = lpips.im2tensor(img_np)                 # torch.Tensor (1,3,H,W) in [-1,1]

# Convert back to numpy array
img_np_converted = lpips.tensor2im(img_t)
```
```

--------------------------------

### Download BAPPS Dataset

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Use this script to download the Berkeley Adobe Perceptual Patch Similarity (BAPPS) dataset. It can download the full dataset or only the validation set.

```bash
bash ./scripts/download_dataset.sh
```

```bash
bash ./scripts/download_dataset_valonly.sh
```

--------------------------------

### Tune Perceptual Metric

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Script to tune the perceptual metric.

```bash
train_test_metric_tune.sh
```

--------------------------------

### Calculate Distances Between Images in Two Directories

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Computes LPIPS distances between corresponding images in two specified directories and writes the results to an output file. The --use_gpu flag is recommended for performance.

```bash
python lpips_2dirs.py \
    -d0 imgs/ex_dir0 \
    -d1 imgs/ex_dir1 \
    -o imgs/example_dists.txt \
    --use_gpu
```

--------------------------------

### Calculate Distances Between Images in Two Directories (Command Line)

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Use the lpips_2dirs.py script to compute perceptual distances between all corresponding image pairs in two directories. Results are saved to an output file.

```bash
python lpips_2dirs.py -d0 imgs/ex_dir0 -d1 imgs/ex_dir1 -o imgs/example_dists.txt --use_gpu
```

--------------------------------

### Load Images and Compute LPIPS Distance

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Loads two images, computes their perceptual distance using the LPIPS metric with the 'alex' network, and prints the results. Ensure images are in the './imgs/' directory.

```python
import lpips

ref  = lpips.im2tensor(lpips.load_image('./imgs/ex_ref.png'))
p0   = lpips.im2tensor(lpips.load_image('./imgs/ex_p0.png'))
p1   = lpips.im2tensor(lpips.load_image('./imgs/ex_p1.png'))

loss_fn = lpips.LPIPS(net='alex')
d0 = loss_fn(ref, p0)
d1 = loss_fn(ref, p1)
print('Distances: (%.3f, %.3f)' % (d0.item(), d1.item()))
```

--------------------------------

### Calculate Distance Between Two Images (Command Line)

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Use the lpips_2imgs.py script to compute the perceptual distance between two specified image files. The --use_gpu flag enables GPU acceleration.

```bash
python lpips_2imgs.py -p0 imgs/ex_ref.png -p1 imgs/ex_p0.png --use_gpu
```

--------------------------------

### lpips.l2 / lpips.psnr / lpips.dssim

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Standalone NumPy-based implementations of L2 distance, Peak Signal-to-Noise Ratio (PSNR), and Structural Dissimilarity (DSSIM). These are useful as baselines alongside the learned LPIPS metric.

```APIDOC
## `lpips.l2` / `lpips.psnr` / `lpips.dssim` – Classical image metrics

Standalone NumPy-based implementations of L2 distance, Peak Signal-to-Noise Ratio (PSNR), and Structural Dissimilarity (DSSIM). Useful as baselines alongside the learned LPIPS metric.

```python
import numpy as np
import lpips

rng = np.random.default_rng(0)
img_a = rng.integers(0, 256, (64, 64, 3), dtype=np.uint8).astype(float)
img_b = rng.integers(0, 256, (64, 64, 3), dtype=np.uint8).astype(float)

l2_score   = lpips.l2(img_a, img_b, range=255.)
psnr_score = lpips.psnr(img_a, img_b, peak=255.)
dssim_val  = lpips.dssim(img_a, img_b, range=255.)   # requires scikit-image

print('L2:    %.4f' % l2_score)    # L2:    0.0833
print('PSNR:  %.2f dB' % psnr_score)   # PSNR:  7.94 dB
print('DSSIM: %.4f' % dssim_val)   # DSSIM: 0.4512
```
```

--------------------------------

### Calculate All Pairwise Distances Within a Directory

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Computes all pairwise LPIPS distances for images within a single directory and saves the results to a file. The --all-pairs and --use_gpu flags are essential for this operation.

```bash
python lpips_1dir_allpairs.py \
    -d imgs/ex_dir_pair \
    -o imgs/example_dists_pair.txt \
    --all-pairs \
    --use_gpu
```

--------------------------------

### LPIPS as a differentiable perceptual loss (backprop)

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

The `lpips.LPIPS` class is a standard `torch.nn.Module`, allowing gradients to flow through it for optimization tasks. Use `net='vgg'` for optimization as it is empirically closer to the traditional VGG perceptual loss. Gradients are computed with respect to the input image.

```APIDOC
## LPIPS as a differentiable perceptual loss (backprop)

`lpips.LPIPS` is a standard `torch.nn.Module`, so gradients flow through it. Use `net='vgg'` for optimization tasks as it is empirically closer to the traditional VGG perceptual loss. Gradients are computed with respect to the input image.

```python
import torch
from torch.autograd import Variable
import lpips

loss_fn = lpips.LPIPS(net='vgg')

ref  = lpips.im2tensor(lpips.load_image('./imgs/ex_ref.png'))
pred = Variable(lpips.im2tensor(lpips.load_image('./imgs/ex_p1.png')),
                requires_grad=True)

optimizer = torch.optim.Adam([pred], lr=1e-3, betas=(0.9, 0.999))

for i in range(200):
    dist = loss_fn(pred, ref)          # perceptual loss
    optimizer.zero_grad()
    dist.backward()
    optimizer.step()
    pred.data = torch.clamp(pred.data, -1, 1)   # keep in valid range

    if i % 50 == 0:
        print('iter %d, perceptual dist: %.4f' % (i, dist.item()))
# iter 0,   perceptual dist: 0.5612
# iter 50,  perceptual dist: 0.3801
# iter 100, perceptual dist: 0.2104
# iter 150, perceptual dist: 0.1347

final_img = lpips.tensor2im(pred.data)   # retrieve optimized image as uint8 array
```
```

--------------------------------

### Evaluate Perceptual Similarity Metric on Dataset

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Evaluate a perceptual similarity model on a subset of the BAPPS dataset. Specify dataset mode, datasets, model type, network architecture, colorspace, batch size, and GPU usage.

```python
python ./test_dataset_model.py --dataset_mode 2afc --datasets val/traditional val/cnn --model lpips --net alex --use_gpu --batch_size 50
```

--------------------------------

### LPIPS as a Differentiable Perceptual Loss

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Demonstrates using LPIPS as a differentiable loss for optimizing an image. Gradients are computed with respect to the input image. Use `net='vgg'` for optimization tasks. The predicted image is clamped to the range [-1, 1].

```python
import torch
from torch.autograd import Variable
import lpips

loss_fn = lpips.LPIPS(net='vgg')

ref  = lpips.im2tensor(lpips.load_image('./imgs/ex_ref.png'))
pred = Variable(lpips.im2tensor(lpips.load_image('./imgs/ex_p1.png')),
                requires_grad=True)

optimizer = torch.optim.Adam([pred], lr=1e-3, betas=(0.9, 0.999))

for i in range(200):
    dist = loss_fn(pred, ref)
    optimizer.zero_grad()
    dist.backward()
    optimizer.step()
    pred.data = torch.clamp(pred.data, -1, 1)

    if i % 50 == 0:
        print('iter %d, perceptual dist: %.4f' % (i, dist.item()))

final_img = lpips.tensor2im(pred.data)
```

--------------------------------

### lpips.LPIPS – Perceptual similarity model

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

The core torch.nn.Module class for computing perceptual distance between image tensors. It supports different pretrained backbones and optional learned linear calibration layers. Images must be RGB tensors of shape (N, 3, H, W) normalized to [-1, 1].

```APIDOC
## lpips.LPIPS

### Description
Computes the perceptual distance between two image tensors.

### Method
```python
loss_fn = lpips.LPIPS(net='alex', version='0.1')
dist = loss_fn(img0, img1)
```

### Parameters
*   **net** (string) - Optional - Backbone network to use ('alex', 'vgg', 'squeeze'). Defaults to 'alex'.
*   **version** (string) - Optional - LPIPS version ('0.1' or '0.0'). Defaults to '0.1'.
*   **lpips** (boolean) - Optional - Whether to use learned linear calibration layers. Defaults to True.
*   **spatial** (boolean) - Optional - If True, returns a per-pixel distance map. Defaults to False.
*   **img0** (torch.Tensor) - Input image tensor (N, 3, H, W) in range [-1, 1].
*   **img1** (torch.Tensor) - Input image tensor (N, 3, H, W) in range [-1, 1].
*   **normalize** (boolean) - Optional - If True, accepts [0, 1] input and rescales to [-1, 1] internally. Defaults to False.
*   **retPerLayer** (boolean) - Optional - If True, returns total distance and per-layer distances. Defaults to False.

### Response
*   **dist** (torch.Tensor) - Scalar perceptual distance (N, 1, 1, 1) or per-pixel distance map (N, 1, H, W) if `spatial=True`.
*   **total_dist** (torch.Tensor) - Total perceptual distance.
*   **per_layer** (list of torch.Tensor) - List of per-layer perceptual distances.

### Request Example
```python
import torch
import lpips

loss_fn = lpips.LPIPS(net='alex')
img0 = torch.rand(1, 3, 64, 64) * 2 - 1
img1 = torch.rand(1, 3, 64, 64) * 2 - 1

dist = loss_fn(img0, img1)
print(dist.item())
```

### Response Example
```
0.5234
```
```

--------------------------------

### Evaluate Distance Function on BAPPS Dataset

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Sets up a distance function (using LPIPS) and prepares it for evaluation against the BAPPS dataset using either 2AFC or JND protocols. The function returns agreement scores and raw data arrays.

```python
import lpips
from data import data_loader as dl

# Load LPIPS model as the distance function
loss_fn = lpips.LPIPS(net='alex', version='0.1')

def dist_fn(in0, in1):
    return loss_fn.forward(in0, in1)
```

--------------------------------

### Calculate LPIPS Distance (Python)

Source: https://github.com/richzhang/perceptualsimilarity/blob/master/README.md

Calculate the perceptual distance between two images using the initialized LPIPS loss function. Images must be RGB and normalized to [-1,1].

```python
import torch
img0 = torch.zeros(1,3,64,64) # image should be RGB, IMPORTANT: normalized to [-1,1]
img1 = torch.zeros(1,3,64,64)
d = loss_fn_alex(img0, img1)
```

--------------------------------

### 2AFC Evaluation with LPIPS

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Evaluates the LPIPS metric on a 2AFC dataset. Requires a DataLoader configured for '2afc' mode. The score represents the fraction of triplets where the metric agreed with human judgments.

```python
data_loader_2afc = dl.CreateDataLoader(
    ['val/traditional', 'val/cnn'],
    dataset_mode='2afc',
    batch_size=50,
    serial_batches=True,
    nThreads=0,
)
score_2afc, info_2afc = lpips.score_2afc_dataset(data_loader_2afc, dist_fn, name='val_2afc')
print('2AFC score: %.4f' % score_2afc)
```

```python
import numpy as np
print('Mean d0:', np.mean(info_2afc['d0s']))
print('Mean d1:', np.mean(info_2afc['d1s']))
```

--------------------------------

### JND Evaluation with LPIPS

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Evaluates the LPIPS metric on a JND (Just Noticeable Difference) dataset. Requires a DataLoader configured for 'jnd' mode. The score is the area under the precision-recall curve.

```python
data_loader_jnd = dl.CreateDataLoader(
    ['val/traditional'],
    dataset_mode='jnd',
    batch_size=1,
    serial_ ইতি,
    nThreads=0,
)
score_jnd, info_jnd = lpips.score_jnd_dataset(data_loader_jnd, dist_fn, name='val_jnd')
print('JND mAP: %.4f' % score_jnd)
```

--------------------------------

### Compute Classical Image Metrics (NumPy)

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Calculates L2 distance, PSNR, and DSSIM between two images using NumPy. DSSIM requires scikit-image. Images should be NumPy arrays of dtype uint8.

```python
import numpy as np
import lpips

rng = np.random.default_rng(0)
img_a = rng.integers(0, 256, (64, 64, 3), dtype=np.uint8).astype(float)
img_b = rng.integers(0, 256, (64, 64, 3), dtype=np.uint8).astype(float)

l2_score   = lpips.l2(img_a, img_b, range=255.)
psnr_score = lpips.psnr(img_a, img_b, peak=255.)
dssim_val  = lpips.dssim(img_a, img_b, range=255.)

print('L2:    %.4f' % l2_score)
print('PSNR:  %.2f dB' % psnr_score)
print('DSSIM: %.4f' % dssim_val)
```

--------------------------------

### Compute Spatial Perceptual Distance Map

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

When `spatial=True`, the LPIPS model returns a per-pixel distance map of shape (N, 1, H, W). This is useful for visualizing areas where two images differ perceptually. Requires matplotlib for visualization.

```python
import torch
import lpips
import matplotlib.pyplot as plt

loss_fn_spatial = lpips.LPIPS(net='alex', spatial=True)

ex_ref = lpips.im2tensor(lpips.load_image('./imgs/ex_ref.png'))   # (1,3,H,W)
ex_p0  = lpips.im2tensor(lpips.load_image('./imgs/ex_p0.png'))

dist_map = loss_fn_spatial(ex_ref, ex_p0)   # shape: (1, 1, H, W)
print('Map shape:', dist_map.shape)          # Map shape: torch.Size([1, 1, 64, 64])
print('Mean distance:', dist_map.mean().item())

# Visualize the spatial distance map
plt.imshow(dist_map[0, 0].detach().cpu().numpy(), cmap='hot')
plt.colorbar()
plt.title('Perceptual distance map')
plt.savefig('dist_map.png')
```

--------------------------------

### score_2afc_dataset / score_jnd_dataset

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Evaluate any distance function against the BAPPS dataset using 2AFC (Two-Alternative Forced Choice) or JND (Just-Noticeable Difference) protocols. These functions return a scalar agreement score and raw arrays.

```APIDOC
## `score_2afc_dataset` / `score_jnd_dataset` – Dataset evaluation

Evaluate any distance function against the BAPPS dataset using 2AFC (Two-Alternative Forced Choice) or JND (Just-Noticeable Difference) protocols. Returns a scalar agreement score and raw arrays.

```python
import lpips
from data import data_loader as dl

# Load LPIPS model as the distance function
loss_fn = lpips.LPIPS(net='alex', version='0.1')

def dist_fn(in0, in1):
    return loss_fn.forward(in0, in1)


```

--------------------------------

### lpips.LPIPS with spatial=True – Spatial distance map

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

When `spatial=True`, the LPIPS model returns a per-pixel distance map of shape (N, 1, H, W) instead of a single scalar per image. This is useful for visualizing where two images differ perceptually.

```APIDOC
## lpips.LPIPS (spatial=True)

### Description
Computes a per-pixel perceptual distance map between two image tensors.

### Method
```python
loss_fn_spatial = lpips.LPIPS(net='alex', spatial=True)
dist_map = loss_fn_spatial(ex_ref, ex_p0)
```

### Parameters
*   **net** (string) - Optional - Backbone network to use ('alex', 'vgg', 'squeeze'). Defaults to 'alex'.
*   **ex_ref** (torch.Tensor) - Reference image tensor (1, 3, H, W) in range [-1, 1].
*   **ex_p0** (torch.Tensor) - Target image tensor (1, 3, H, W) in range [-1, 1].

### Response
*   **dist_map** (torch.Tensor) - Per-pixel distance map of shape (N, 1, H, W).

### Request Example
```python
import torch
import lpips
import matplotlib.pyplot as plt

loss_fn_spatial = lpips.LPIPS(net='alex', spatial=True)
ex_ref = lpips.im2tensor(lpips.load_image('./imgs/ex_ref.png'))
ex_p0  = lpips.im2tensor(lpips.load_image('./imgs/ex_p0.png'))

dist_map = loss_fn_spatial(ex_ref, ex_p0)

plt.imshow(dist_map[0, 0].detach().cpu().numpy(), cmap='hot')
plt.colorbar()
plt.title('Perceptual distance map')
plt.savefig('dist_map.png')
```
```

--------------------------------

### lpips.normalize_tensor

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Normalizes a feature tensor along the channel dimension to unit length (L2 norm). This is used internally during the forward pass to compute cosine-distance-like feature differences.

```APIDOC
## `lpips.normalize_tensor` – Feature normalization utility

Normalizes a feature tensor along the channel dimension to unit length (L2 norm). Used internally during the forward pass to compute cosine-distance-like feature differences.

```python
import torch
import lpips

feat = torch.randn(2, 256, 16, 16)
normed = lpips.normalize_tensor(feat, eps=1e-10)

# Verify unit norm along channel dimension
norms = torch.sqrt((normed ** 2).sum(dim=1))
print(norms.shape)        # torch.Size([2, 16, 16])
print(norms.min().item(), norms.max().item())   # ~1.0  ~1.0
```
```

--------------------------------

### Normalize Feature Tensor

Source: https://context7.com/richzhang/perceptualsimilarity/llms.txt

Normalizes a feature tensor along the channel dimension to unit length using L2 norm. This is used internally for cosine-distance-like feature differences. The `eps` parameter prevents division by zero.

```python
import torch
import lpips

feat = torch.randn(2, 256, 16, 16)
normed = lpips.normalize_tensor(feat, eps=1e-10)

# Verify unit norm along channel dimension
norms = torch.sqrt((normed ** 2).sum(dim=1))
print(norms.shape)
print(norms.min().item(), norms.max().item())
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.