# examples/dinov2_features.py
"""Extract original, released DINOv2 ViT-S/14 features from real images.

The local-only route requires both an exact upstream git checkout and the
released checkpoint. A failed source or checkpoint load is never replaced by
random weights. Retrieval, PCA, and export are separate consumers of this core.
"""

import argparse
import hashlib
import json
import os
import platform
import shutil
import subprocess
import tempfile
import zipfile
from collections.abc import Sequence
from pathlib import Path

import numpy as np
import PIL
import torch
import torchvision
from PIL import Image, ImageOps
from torch import Tensor, nn
from torchvision import transforms
from torchvision.transforms import InterpolationMode

CODE_REVISION = "7764ea0f912e53c92e82eb78a2a1631e92725fc8"
SOURCE_REPOSITORY = "https://github.com/facebookresearch/dinov2"
WEIGHTS_URL = (
    "https://dl.fbaipublicfiles.com/dinov2/dinov2_vits14/"
    "dinov2_vits14_pretrain.pth"
)
WEIGHTS_SHA256 = (
    "b938bf1bc15cd2ec0feacfe3a1bb553fe8ea9ca46a7e1d8d00217f29aef60cd9"
)
SUPPORTED_SUFFIXES = {
    ".jpg",
    ".jpeg",
    ".png",
    ".webp",
    ".bmp",
    ".tif",
    ".tiff",
}
MAX_PIXELS = 25_000_000
IMAGENET_MEAN = (0.485, 0.456, 0.406)
IMAGENET_STD = (0.229, 0.224, 0.225)


def sha256_file(path: Path) -> str:
    """Return the SHA-256 of a file without reading it all into memory."""
    digest = hashlib.sha256()
    with Path(path).open("rb") as stream:
        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def _read_rgb(path: Path) -> Image.Image:
    """Read a bounded image, orient it, and name the input on any decode error."""
    try:
        with Image.open(path) as image:
            width, height = image.size
            if width * height > MAX_PIXELS:
                raise ValueError(f"{path}: image exceeds 25 megapixels")
            # Inspect dimensions before any pixel decode, RGB copy, or tensor.
            return ImageOps.exif_transpose(image).convert("RGB")
    except (OSError, ValueError, Image.DecompressionBombError) as error:
        raise ValueError(f"{path}: cannot decode image: {error}") from error


def _validate_group(group: dict, image_ids: set[str]) -> None:
    """Validate a group against the decoded gallery IDs."""
    ids = group.get("imageIds", [])
    if len(ids) < 3 or len(set(ids)) != len(ids):
        raise ValueError("PCA group requires at least three unique image IDs")
    missing = set(ids) - image_ids
    if missing:
        raise ValueError(f"Unknown PCA image IDs: {sorted(missing)}")
    if not group.get("id"):
        raise ValueError("PCA group requires an ID")


def read_image_inputs(
    directory: Path, pca_images: Sequence[str] | None = None
) -> dict:
    """Resolve 3–64 deterministic, RGB-decodable inputs and PCA groups.

    Args:
        directory: Input folder, optionally containing the sample manifest.
        pca_images: Explicit IDs for a single override group.

    Returns:
        A dictionary with sorted ``images``, resolved ``pcaGroups``, and the
        actual ``directory`` for optional supplied-gallery packaging.

    Raises:
        ValueError: Invalid IDs, image counts, dimensions, hashes, or groups.
    """
    directory = Path(directory).expanduser().resolve()
    manifest_path = directory / "manifest.json"
    if manifest_path.is_file():
        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
        entries = manifest["images"]
        groups = manifest.get("pcaGroups", [])
    else:
        entries = [
            {"id": path.stem, "path": str(path.relative_to(directory))}
            for path in sorted(directory.rglob("*"))
            if path.is_file() and path.suffix.lower() in SUPPORTED_SUFFIXES
        ]
        groups = []
    if not 3 <= len(entries) <= 64:
        raise ValueError(
            "Image directory must contain between 3 and 64 images"
        )
    ids = [entry["id"] for entry in entries]
    if len(set(ids)) != len(ids):
        duplicates = sorted(
            {image_id for image_id in ids if ids.count(image_id) > 1}
        )
        raise ValueError(f"duplicate image IDs: {duplicates}")
    records = []
    for entry in sorted(entries, key=lambda row: row["id"]):
        image_id = entry["id"]
        if (
            not isinstance(image_id, str)
            or not image_id
            or image_id in {".", ".."}
            or "/" in image_id
            or "\\" in image_id
        ):
            raise ValueError(f"Invalid image ID: {image_id!r}")
        path = (directory / entry["path"]).resolve()
        if not path.is_relative_to(directory):
            raise ValueError(f"Image path is outside input directory: {path}")
        _read_rgb(path)
        digest = sha256_file(path)
        if entry.get("sourceSha256") and entry["sourceSha256"] != digest:
            raise ValueError(f"Image hash mismatch: {path}")
        records.append(
            {
                "id": image_id,
                "path": path,
                "sourceSha256": digest,
                "groupIds": entry.get("groupIds", []),
                "attribution": entry.get("attribution", {}),
            }
        )
    sorted_ids = [record["id"] for record in records]
    if pca_images is not None:
        groups = [{"id": "explicit", "imageIds": list(pca_images)}]
    elif not groups:
        groups = [{"id": "default", "imageIds": sorted_ids[:3]}]
    if len({group["id"] for group in groups}) != len(groups):
        raise ValueError("duplicate PCA group IDs")
    for group in groups:
        _validate_group(group, set(sorted_ids))
    return {"images": records, "pcaGroups": groups, "directory": directory}


def preprocess_image(path: Path) -> tuple[Tensor, Image.Image]:
    """Return ImageNet-normalized input and its exact unnormalized RGB crop."""
    image = _read_rgb(Path(path))
    width, height = image.size
    short_edge, long_edge = sorted((width, height))
    # Match torchvision's scalar Resize rounding without allocating its result.
    resized_long_edge = int(256 * long_edge / short_edge)
    resized_size = (
        (256, resized_long_edge)
        if width <= height
        else (resized_long_edge, 256)
    )
    if resized_size[0] * resized_size[1] > MAX_PIXELS:
        raise ValueError(
            f"{path}: resized image exceeds 25 megapixels "
            f"({resized_size[0]} x {resized_size[1]})"
        )
    crop = transforms.CenterCrop(224)(
        transforms.Resize(256, interpolation=InterpolationMode.BICUBIC)(image)
    )
    tensor = transforms.Normalize(IMAGENET_MEAN, IMAGENET_STD)(
        transforms.ToTensor()(crop)
    )
    return tensor, crop


def load_backbone(
    device: str, repo_dir: Path | None = None, weights: Path | None = None
) -> tuple[nn.Module, dict]:
    """Load exact upstream architecture with strict official LVD-142M weights.

    Args:
        device: ``cpu`` or a PyTorch CUDA device, using float32 inference.
        repo_dir: Exact git checkout for local-only operation.
        weights: Official checkpoint path, required together with repo_dir.

    Returns:
        The evaluation-mode model and provenance/runtime metadata.

    Raises:
        ValueError: Unpaired local inputs, wrong revision or checkpoint digest.
        RuntimeError: Source loading or strict state-dict loading failed.
    """
    if (repo_dir is None) != (weights is None):
        raise ValueError(
            "Local-only loading requires both repo_dir and weights"
        )
    # Official code supports native attention, including on CPU, with this flag.
    os.environ["XFORMERS_DISABLED"] = "1"
    if repo_dir is not None:
        repo_dir = Path(repo_dir).expanduser().resolve()
        revision = subprocess.run(
            ["git", "-C", str(repo_dir), "rev-parse", "HEAD"],
            check=False,
            capture_output=True,
            text=True,
        )
        if revision.returncode or revision.stdout.strip() != CODE_REVISION:
            raise ValueError(
                f"Local source revision must be {CODE_REVISION}: {repo_dir}"
            )
        dirty = subprocess.run(
            [
                "git",
                "-C",
                str(repo_dir),
                "status",
                "--porcelain",
                "--untracked-files=no",
            ],
            check=True,
            capture_output=True,
            text=True,
        )
        if dirty.stdout.strip():
            raise ValueError(
                f"Local source revision has modified tracked files: {repo_dir}"
            )
        weights_path = Path(weights).expanduser().resolve()
        digest = sha256_file(weights_path)
        if digest != WEIGHTS_SHA256:
            raise ValueError(
                f"Official weights SHA-256 mismatch: {weights_path}"
            )
        model = torch.hub.load(
            str(repo_dir), "dinov2_vits14", source="local", pretrained=False
        )
        source_origin = str(repo_dir)
    else:
        model = torch.hub.load(
            f"facebookresearch/dinov2:{CODE_REVISION}",
            "dinov2_vits14",
            pretrained=False,
            trust_repo=True,
            skip_validation=True,
        )
        checkpoint_dir = Path(torch.hub.get_dir()) / "checkpoints"
        checkpoint_dir.mkdir(parents=True, exist_ok=True)
        weights_path = checkpoint_dir / "dinov2_vits14_pretrain.pth"
        if not weights_path.is_file():
            # Download to a temporary name, so failed requests do not poison cache.
            temporary = weights_path.with_suffix(".download")
            try:
                torch.hub.download_url_to_file(
                    WEIGHTS_URL, str(temporary), progress=True
                )
                if sha256_file(temporary) != WEIGHTS_SHA256:
                    raise ValueError(
                        "Downloaded official weights SHA-256 mismatch"
                    )
                temporary.replace(weights_path)
            finally:
                temporary.unlink(missing_ok=True)
        digest = sha256_file(weights_path)
        if digest != WEIGHTS_SHA256:
            raise ValueError(
                f"Official weights SHA-256 mismatch: {weights_path}"
            )
        source_origin = f"{SOURCE_REPOSITORY}/tree/{CODE_REVISION}"
    state = torch.load(weights_path, map_location="cpu", weights_only=True)
    model.load_state_dict(state, strict=True)
    model = model.to(device=device, dtype=torch.float32).eval()
    metadata = {
        "model": "dinov2_vits14",
        "dataset": "LVD-142M",
        "codeRevision": CODE_REVISION,
        "sourceRepository": SOURCE_REPOSITORY,
        "sourceOrigin": source_origin,
        "weightsUrl": WEIGHTS_URL,
        "weightsSha256": digest,
        "runtime": {
            "python": platform.python_version(),
            "torch": torch.__version__,
            "torchvision": torchvision.__version__,
            "numpy": np.__version__,
            "Pillow": PIL.__version__,
            "device": str(device),
            "dtype": "float32",
            "attention": "native",
            "xformersDisabled": True,
        },
        "preprocessing": {
            "resizeShortEdge": 256,
            "interpolation": "bicubic",
            "cropSize": 224,
            "mean": list(IMAGENET_MEAN),
            "std": list(IMAGENET_STD),
            "exifOrientation": True,
            "mode": "RGB",
        },
    }
    return model, metadata


def extract_features(
    model: nn.Module, inputs: Sequence[Tensor], device: str
) -> dict[str, Tensor]:
    """Infer image and patch features as CPU float32 tensors without gradients."""
    if not inputs:
        raise ValueError("Feature extraction requires at least one input")
    model.eval()
    cls_features, patch_features = [], []
    with torch.inference_mode():
        # Single-image batches bound activation memory for reader galleries.
        for tensor in inputs:
            if tuple(tensor.shape) != (3, 224, 224):
                raise ValueError("Feature inputs must have shape [3,224,224]")
            # region: features
            result = model.forward_features(
                tensor.unsqueeze(0).to(device=device, dtype=torch.float32)
            )
            cls_features.append(result["x_norm_clstoken"].cpu())
            patch_features.append(result["x_norm_patchtokens"].cpu())
            # endregion: features
        features = {
            "cls": torch.cat(cls_features),
            "patches": torch.cat(patch_features),
        }
    expected = {"cls": (len(inputs), 384), "patches": (len(inputs), 256, 384)}
    for name, tensor in features.items():
        if (
            tuple(tensor.shape) != expected[name]
            or not torch.isfinite(tensor).all()
        ):
            raise ValueError(f"Invalid released-model {name} features")
    return features


SIGN_RULE = "largest-absolute-loading-positive"
IMAGE_PUBLIC_ROOT = "/images/papers/dinov2/generated"
DEMO_PUBLIC_ROOT = "/examples/dinov2-demo"


def rank_neighbors(
    cls_features: Tensor, image_ids: Sequence[str]
) -> dict[str, list[dict]]:
    """Return full-precision normalized cosine ranks, breaking ties by ID."""
    vectors = cls_features.detach().to(device="cpu", dtype=torch.float64)
    if vectors.shape != (len(image_ids), 384) or len(set(image_ids)) != len(
        image_ids
    ):
        raise ValueError("CLS features require one unique ID per [I,384] row")
    norms = vectors.norm(dim=1, keepdim=True)
    if not torch.isfinite(vectors).all() or (norms == 0).any():
        raise ValueError(
            "Cosine retrieval requires finite nonzero CLS vectors"
        )
    # region: retrieval
    normalized = vectors / norms
    similarities = normalized @ normalized.T
    queries = {}
    for index, query in enumerate(image_ids):
        neighbors = [
            {"imageId": image_id, "score": similarities[index, other].item()}
            for other, image_id in enumerate(image_ids)
            if other != index
        ]
        queries[query] = sorted(
            neighbors, key=lambda row: (-row["score"], row["imageId"])
        )
    # endregion: retrieval
    return queries


def scale_rgb(scores: Tensor) -> Tensor:
    """Scale shared retained scores to uint8, using 128 for constant channels."""
    if scores.ndim != 2 or scores.shape[1] != 3 or not len(scores):
        raise ValueError("RGB scores require a nonempty [M,3] matrix")
    if not torch.isfinite(scores).all():
        raise ValueError("RGB scores must be finite")
    minimum, maximum = scores.amin(dim=0), scores.amax(dim=0)
    spread = maximum - minimum
    scaled = (
        (scores - minimum)
        / spread.clamp_min(torch.finfo(scores.dtype).tiny)
        * 255
    ).round()
    scaled[:, spread == 0] = 128
    return scaled.clamp(0, 255).to(torch.uint8)


def _fit_basis(rows: Tensor, components: int) -> dict:
    """Fit deterministic centered full SVD and orient the requested loadings."""
    mean = rows.mean(dim=0)
    centered = rows - mean
    _, singular_values, loadings = torch.linalg.svd(
        centered, full_matrices=False
    )
    tolerance = (
        max(centered.shape)
        * torch.finfo(centered.dtype).eps
        * singular_values[0].item()
    )
    rank = int((singular_values > tolerance).sum().item())
    loadings = loadings[:components].clone()
    largest_indices = loadings.abs().argmax(dim=1)
    signs = torch.sign(loadings[torch.arange(len(loadings)), largest_indices])
    loadings *= signs[:, None]
    return {
        "mean": mean,
        "loadings": loadings,
        "singularValues": singular_values,
        "matrixShape": list(rows.shape),
        "rank": rank,
        "rankTolerance": tolerance,
        "signRule": SIGN_RULE,
    }


def fit_patch_pca(
    patches: Tensor, image_ids: Sequence[str], threshold: float = 0.0
) -> dict:
    """Fit a shared foreground selector and an independent RGB PCA per side.

    Input patches are already selected for one image group. Fits and projections
    run on CPU float64. Returned tensors are consumed by the exporter; browser
    metadata references their keys instead of serializing raw basis arrays.
    """
    if not np.isfinite(threshold):
        raise ValueError("Foreground threshold must be finite")
    if patches.shape != (len(image_ids), 256, 384) or not image_ids:
        raise ValueError("Patch PCA requires one ID per [J,256,384] image")
    if (
        len(set(image_ids)) != len(image_ids)
        or not torch.isfinite(patches).all()
    ):
        raise ValueError("Patch PCA requires unique IDs and finite features")
    rows = (
        patches.detach().to(device="cpu", dtype=torch.float64).reshape(-1, 384)
    )
    # region: pca
    first_basis = _fit_basis(rows, 1)
    first_scores = ((rows - first_basis["mean"]) @ first_basis["loadings"].T)[
        :, 0
    ]
    variants = {}
    for side in ("positive", "negative"):
        mask = (
            first_scores > threshold
            if side == "positive"
            else first_scores < threshold
        )
        retained = rows[mask]
        variant = {
            "masks": mask.reshape(len(image_ids), 16, 16),
            "retainedCount": len(retained),
            "secondBasis": None,
        }
        if first_basis["rank"] == 0:
            variant.update(
                status="degenerate_features",
                message="The shared first PCA has no nonzero direction.",
            )
        elif len(retained) < 4:
            variant.update(
                status="insufficient_foreground",
                message="This threshold side retains fewer than four patches.",
            )
        else:
            second_basis = _fit_basis(retained, 3)
            variant["secondBasis"] = second_basis
            if second_basis["rank"] < 3:
                variant.update(
                    status="degenerate_features",
                    message=(
                        "The retained patches have fewer than three "
                        "nonzero PCA directions."
                    ),
                )
            else:
                scores = (retained - second_basis["mean"]) @ second_basis[
                    "loadings"
                ].T
                colors = scale_rgb(scores)
                rgba = torch.zeros(len(rows), 4, dtype=torch.uint8)
                rgba[mask, :3] = colors
                rgba[mask, 3] = 255
                variant.update(
                    status="ok",
                    message=(
                        "Separate shared PCA fitted to this retained "
                        "threshold side."
                    ),
                    rgba=rgba.reshape(len(image_ids), 16, 16, 4),
                    channelMin=scores.amin(dim=0),
                    channelMax=scores.amax(dim=0),
                )
        variants[side] = variant
    # endregion: pca
    return {
        "imageIds": list(image_ids),
        "firstBasis": first_basis,
        "variants": variants,
    }


def _basis_metadata(
    basis: dict | None, prefix: str, tensors: dict
) -> dict | None:
    """Move full bases to tensor-only storage and describe them compactly."""
    if basis is None:
        return None
    keys = {}
    for field in ("mean", "loadings", "singularValues"):
        key = f"{prefix}.{field}"
        tensors[key] = basis[field]
        keys[field] = key
    variance = basis["singularValues"].square()
    total = variance.sum().item()
    summaries = []
    for index, loading in enumerate(basis["loadings"]):
        largest = loading.abs().argmax().item()
        summaries.append(
            {
                "singularValue": basis["singularValues"][index].item(),
                "explainedVarianceRatio": (
                    variance[index].item() / total if total else 0.0
                ),
                "largestLoadingIndex": largest,
                "largestLoading": loading[largest].item(),
            }
        )
    return {
        "matrixShape": basis["matrixShape"],
        "meanShape": list(basis["mean"].shape),
        "loadingsShape": list(basis["loadings"].shape),
        "rank": basis["rank"],
        "rankTolerance": basis["rankTolerance"],
        "signRule": basis["signRule"],
        "tensorKeys": keys,
        "componentSummaries": summaries,
    }


def _sample_archive(destination: Path, sample: Path) -> None:
    """Encode the supplied input bundle, preserving canonical ZIP bytes."""
    paths = [sample / "LICENSES.md", sample / "manifest.json"]
    manifest = json.loads(
        (sample / "manifest.json").read_text(encoding="utf-8")
    )
    paths.extend(
        _local_asset(sample, image["path"]) for image in manifest["images"]
    )
    with zipfile.ZipFile(
        destination, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=9
    ) as archive:
        for path in sorted(
            paths, key=lambda item: item.relative_to(sample).as_posix()
        ):
            info = zipfile.ZipInfo(
                path.relative_to(sample).as_posix(),
                date_time=(1980, 1, 1, 0, 0, 0),
            )
            info.compress_type = zipfile.ZIP_DEFLATED
            info.external_attr = 0o100644 << 16
            info.create_system = 3
            archive.writestr(info, path.read_bytes(), compresslevel=9)


def _local_asset(directory: Path, relative_path: str) -> Path:
    """Reject absolute or escaping integrity paths, including symlink escapes."""
    relative = Path(relative_path)
    target = (directory / relative).resolve()
    if (
        relative.is_absolute()
        or ".." in relative.parts
        or not target.is_relative_to(directory.resolve())
    ):
        raise ValueError(f"Unsafe export relativePath: {relative_path}")
    return target


def validate_export(directory: Path) -> dict:
    """Check complete artifact hashes, images, and safe tensor round trips."""
    directory = Path(directory)
    manifest = json.loads(
        (directory / "manifest.json").read_text(encoding="utf-8")
    )
    tensors = torch.load(
        directory / "features.pt", map_location="cpu", weights_only=True
    )
    if not isinstance(tensors, dict) or not all(
        isinstance(value, Tensor) and torch.isfinite(value).all()
        for value in tensors.values()
    ):
        raise ValueError("Export features.pt must contain finite tensors only")
    ids = [image["id"] for image in manifest["images"]]
    if tensors["cls"].shape != (len(ids), 384) or tensors["patches"].shape != (
        len(ids),
        256,
        384,
    ):
        raise ValueError("Export features have invalid shapes")
    for record in manifest["integrity"]["assets"]:
        path = _local_asset(directory, record["relativePath"])
        if sha256_file(path) != record["sha256"]:
            raise ValueError(f"Export asset checksum mismatch: {path}")
    by_src = {
        record["src"]: record for record in manifest["integrity"]["assets"]
    }
    for image in manifest["images"]:
        with Image.open(
            _local_asset(directory, by_src[image["cropSrc"]]["relativePath"])
        ) as crop:
            if crop.mode != "RGB" or crop.size != (224, 224):
                raise ValueError("Export crop must be RGB 224x224")
    if manifest["sampleArchive"] is not None:
        if (
            sha256_file(directory / "dinov2-sample-images.zip")
            != manifest["sampleArchive"]["sha256"]
        ):
            raise ValueError("Export sample archive checksum mismatch")
    for query in ids:
        ranked = manifest["retrieval"]["queries"][query]
        if len(ranked) != len(ids) - 1 or {
            row["imageId"] for row in ranked
        } != set(ids) - {query}:
            raise ValueError(
                "Export rankings must exclude each query exactly once"
            )
    for group in manifest["pca"]["groups"]:
        for basis in [
            group["firstBasis"],
            *[
                variant["secondBasis"]
                for variant in group["variants"].values()
            ],
        ]:
            if basis is not None and any(
                key not in tensors for key in basis["tensorKeys"].values()
            ):
                raise ValueError("Export basis tensor key missing")
        for variant in group["variants"].values():
            if variant["status"] != "ok":
                if variant["images"] or not variant["message"]:
                    raise ValueError(
                        "Unavailable PCA cannot contain invented images"
                    )
                continue
            if [image["imageId"] for image in variant["images"]] != group[
                "imageIds"
            ]:
                raise ValueError("Export PCA images do not match group")
            for image in variant["images"]:
                for field, mode in [("maskSrc", "L"), ("colorSrc", "RGBA")]:
                    path = _local_asset(
                        directory, by_src[image[field]]["relativePath"]
                    )
                    with Image.open(path) as asset:
                        if asset.size != (16, 16) or asset.mode != mode:
                            raise ValueError(
                                "Export PCA images must be 16x16 masks/RGBA"
                            )
                        if mode == "L" and not set(
                            np.unique(np.asarray(asset))
                        ).issubset({0, 255}):
                            raise ValueError("Export masks must be binary")
    return manifest


def _write_export(
    directory: Path,
    inputs: dict,
    features: dict,
    model: dict,
    retrieval: dict,
    pca: dict,
) -> None:
    """Write artifacts inside an unpublished staging directory."""
    (directory / "images").mkdir()
    tensors = {
        name: value.detach().cpu().contiguous()
        for name, value in features.items()
    }
    assets, images, groups = [], [], []

    def asset(relative: str) -> str:
        src = (
            f"{IMAGE_PUBLIC_ROOT}/{Path(relative).name}"
            if relative.startswith("images/")
            else f"{DEMO_PUBLIC_ROOT}/{relative}"
        )
        assets.append(
            {
                "src": src,
                "relativePath": relative,
                "sha256": sha256_file(_local_asset(directory, relative)),
            }
        )
        return src

    for index, record in enumerate(inputs["images"]):
        if sha256_file(record["path"]) != record["sourceSha256"]:
            raise ValueError(
                f"Input hash mismatch since inference: {record['path']}"
            )
        _, crop = preprocess_image(record["path"])
        relative = f"images/crop-{index:02d}.png"
        crop.save(directory / relative)
        attribution = record["attribution"]
        images.append(
            {
                "id": record["id"],
                "cropSrc": asset(relative),
                "cropWidth": 224,
                "cropHeight": 224,
                "inputSha256": record["sourceSha256"],
                "sourceUrl": attribution.get("sourceUrl", ""),
                "author": attribution.get("author", ""),
                "license": attribution.get("license", ""),
                "groupIds": [
                    group["id"]
                    for group in pca["groups"]
                    if record["id"] in group["imageIds"]
                ],
            }
        )
    for index, group in enumerate(pca["groups"]):
        variants = {}
        first_basis = _basis_metadata(
            group["firstBasis"], f"pca.{index}.first", tensors
        )
        for side, variant in group["variants"].items():
            exported = {
                field: variant[field]
                for field in ("status", "message", "retainedCount")
            }
            prefix = f"pca.{index}.{side}"
            exported["secondBasis"] = _basis_metadata(
                variant["secondBasis"], prefix, tensors
            )
            tensors[f"{prefix}.masks"] = variant["masks"]
            exported["images"] = []
            if variant["status"] == "ok":
                tensors[f"{prefix}.channelMin"] = variant["channelMin"]
                tensors[f"{prefix}.channelMax"] = variant["channelMax"]
                for image_index, image_id in enumerate(group["imageIds"]):
                    mask_relative = (
                        f"images/pca-{index}-{side}-{image_index}-mask.png"
                    )
                    color_relative = (
                        f"images/pca-{index}-{side}-{image_index}-color.png"
                    )
                    Image.fromarray(
                        (
                            variant["masks"][image_index].to(torch.uint8) * 255
                        ).numpy()
                    ).save(directory / mask_relative)
                    Image.fromarray(variant["rgba"][image_index].numpy()).save(
                        directory / color_relative
                    )
                    exported["images"].append(
                        {
                            "imageId": image_id,
                            "maskSrc": asset(mask_relative),
                            "colorSrc": asset(color_relative),
                        }
                    )
            variants[side] = exported
        groups.append(
            {
                "id": group["id"],
                "imageIds": group["imageIds"],
                "firstBasis": first_basis,
                "variants": variants,
            }
        )
    torch.save(tensors, directory / "features.pt")
    asset("features.pt")
    # Logical source identities stay stable; physical paths follow downloads
    # and the chosen inputs, independent of repository or folder names.
    script = Path(__file__).resolve()
    source_paths = [("examples/dinov2_features.py", script)]
    requirements = script.parent / "requirements-dinov2-features.txt"
    if requirements.is_file():
        source_paths.append(
            ("examples/requirements-dinov2-features.txt", requirements)
        )
    sample = inputs["directory"]
    sample_archive = None
    if (sample / "manifest.json").is_file() and (
        sample / "LICENSES.md"
    ).is_file():
        archive = directory / "dinov2-sample-images.zip"
        _sample_archive(archive, sample)
        sample_archive = {
            "src": asset(archive.name),
            "sha256": sha256_file(archive),
        }
        source_paths.extend(
            (f"examples/dinov2-sample-images/{name}", sample / name)
            for name in ("manifest.json", "LICENSES.md")
        )
    runtime = model["runtime"]
    manifest = {
        "schemaVersion": 1,
        "model": {
            "name": model["model"],
            "codeRevision": model["codeRevision"],
            "weightsUrl": model["weightsUrl"],
            "weightsSha256": model["weightsSha256"],
            "featureDim": 384,
            "patchSize": 14,
            "registerCount": 0,
        },
        "runtime": {
            "python": runtime["python"],
            "packages": {
                name: runtime[name]
                for name in ("torch", "torchvision", "numpy", "Pillow")
            },
            "inferenceDevice": runtime["device"],
            "inferenceDtype": runtime["dtype"],
            "pcaDevice": "cpu",
            "pcaDtype": "float64",
            "preprocessing": model["preprocessing"],
        },
        "images": images,
        "retrieval": {"normalization": "l2-cls", "queries": retrieval},
        "pca": {
            "threshold": pca["threshold"],
            "signRule": SIGN_RULE,
            "defaultGroupId": groups[0]["id"],
            "groups": groups,
        },
        "integrity": {
            "sourceFiles": [
                {"path": identity, "sha256": sha256_file(path)}
                for identity, path in source_paths
            ],
            "assets": assets,
        },
        "sampleArchive": sample_archive,
    }
    (directory / "manifest.json").write_text(
        json.dumps(manifest, indent=2, allow_nan=False) + "\n",
        encoding="utf-8",
    )


def export_demo(
    output: Path,
    inputs: dict,
    features: dict,
    model: dict,
    retrieval: dict,
    pca: dict,
) -> Path:
    """Validate a complete staged export before atomically naming a new output.

    Existing nonempty destinations are never modified. Any write or validation
    failure removes staging only, leaving existing files and public demos alone.
    A manifest plus LICENSES.md in the input folder enables sample packaging;
    ordinary photo exports have sampleArchive=null and no sample ZIP. Source
    receipts include a requirements sidecar only when one is beside this script.
    """
    output = Path(output).expanduser().resolve()
    if output.exists() and (not output.is_dir() or any(output.iterdir())):
        raise ValueError(f"Refusing existing nonempty output: {output}")
    output.parent.mkdir(parents=True, exist_ok=True)
    staging = Path(
        tempfile.mkdtemp(prefix=f".{output.name}-", dir=output.parent)
    )
    try:
        _write_export(staging, inputs, features, model, retrieval, pca)
        validate_export(staging)
        # Removing an existing empty directory happens only after validation.
        if output.exists():
            output.rmdir()
        staging.rename(output)
    finally:
        if staging.exists():
            shutil.rmtree(staging)
    return output / "manifest.json"


def main(argv: Sequence[str] | None = None) -> int:
    """Run real released features, retrieval, shared PCA, and an atomic export."""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument("--images", type=Path, required=True)
    parser.add_argument("--output", type=Path, required=True)
    parser.add_argument("--device", default="cpu")
    parser.add_argument(
        "--pca-images", nargs="+", help="At least three input image IDs"
    )
    parser.add_argument("--foreground-threshold", type=float, default=0.0)
    parser.add_argument("--repo-dir", type=Path)
    parser.add_argument("--weights", type=Path)
    args = parser.parse_args(argv)
    if not np.isfinite(args.foreground_threshold):
        raise ValueError("Foreground threshold must be finite")
    if (args.repo_dir is None) != (args.weights is None):
        raise ValueError(
            "Local-only loading requires both --repo-dir and --weights"
        )
    if args.output.exists() and (
        not args.output.is_dir() or any(args.output.iterdir())
    ):
        raise ValueError(f"Refusing existing nonempty output: {args.output}")
    inputs = read_image_inputs(args.images, args.pca_images)
    model, metadata = load_backbone(args.device, args.repo_dir, args.weights)
    prepared = [
        preprocess_image(image["path"])[0] for image in inputs["images"]
    ]
    extracted = extract_features(model, prepared, args.device)
    ids = [image["id"] for image in inputs["images"]]
    retrieval = rank_neighbors(extracted["cls"], ids)
    groups = []
    for group in inputs["pcaGroups"]:
        selected = [ids.index(image_id) for image_id in group["imageIds"]]
        fitted = fit_patch_pca(
            extracted["patches"][selected],
            group["imageIds"],
            args.foreground_threshold,
        )
        fitted["id"] = group["id"]
        groups.append(fitted)
    manifest = export_demo(
        args.output,
        inputs,
        extracted,
        metadata,
        retrieval,
        {"threshold": args.foreground_threshold, "groups": groups},
    )
    print(f"Validated export: {manifest}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
