imgcheck 0.1.0__py3-none-any.whl

imgcheck/__init__.py

@@ -0,0 +1,9 @@
+"""imgcheck: perceptual-hash based image deduplication and
+train/test leakage detection for image classification datasets.
+"""
+
+__version__ = "0.1.0"
+__authors__ = [
+    ("Rama Narasimha Kanduri", "kramanarasimha1@gmail.com"),
+    ("CS Hari Krishna", "csharikrishna1806@gmail.com"),
+]

imgcheck/clean.py

@@ -0,0 +1,262 @@
+"""Within-class duplicate cleaning.
+
+Copies each unique image (by perceptual hash) into a clean output
+dataset, skipping near-duplicates. Never touches the source dataset —
+always copies, never deletes.
+
+Duplicates are found by transitive clustering (see grouping.py) rather
+than a linear "compare against accepted originals" scan, so a chain of
+near-duplicates (A~B, B~C) always collapses into one group with one
+kept image, regardless of file discovery order.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+
+import pandas as pd
+
+from .grouping import DuplicateCluster, cluster_duplicates
+from .hashing import DEFAULT_EXTENSIONS, HASH_ALGORITHMS, compute_hashes, get_image_paths
+
+
+def _unique_dst_path(dst_dir: str, filename: str) -> str:
+    dst_path = os.path.join(dst_dir, filename)
+    if not os.path.exists(dst_path):
+        return dst_path
+    name, ext = os.path.splitext(filename)
+    counter = 1
+    while os.path.exists(dst_path):
+        dst_path = os.path.join(dst_dir, f"{name}_{counter}{ext}")
+        counter += 1
+    return dst_path
+
+
+def clean_duplicates(
+    dataset_path: str,
+    clean_dataset_path: str,
+    report_path: str,
+    threshold: int = 3,
+    algo: str = "phash",
+    extensions=DEFAULT_EXTENSIONS,
+    pdf_report_path: str | None = None,
+    html_report_path: str | None = None,
+    extra_formats: list[str] | None = None,
+) -> dict:
+    """Walk each class folder under dataset_path, cluster perceptually-
+    duplicate images together (transitively — see grouping.py), keep
+    one representative per cluster, and copy survivors into
+    clean_dataset_path (mirroring the class subfolder structure).
+
+    Writes an Excel report with two sheets:
+      - "Duplicate Count": per-class duplicate counts + TOTAL
+      - "Matches": every kept/duplicate pair, with a shared Cluster ID
+                    so transitively-related duplicates can be told
+                    apart from coincidental pairs
+
+    Optional outputs:
+      - pdf_report_path: visual PDF (requires `fpdf2`, pip install imgcheck[pdf])
+      - html_report_path: self-contained HTML gallery grouped by cluster
+      - extra_formats: e.g. ["csv", "json"] — also export the two
+                        report tables in these formats alongside Excel
+
+    Returns {class_name: duplicate_count}.
+    """
+    if algo not in HASH_ALGORITHMS:
+        raise ValueError(f"Unknown hash algorithm '{algo}'. Choose from {list(HASH_ALGORITHMS)}")
+
+    os.makedirs(clean_dataset_path, exist_ok=True)
+    class_folders = [d for d in os.listdir(dataset_path) if os.path.isdir(os.path.join(dataset_path, d))]
+    for cls in class_folders:
+        os.makedirs(os.path.join(clean_dataset_path, cls), exist_ok=True)
+
+    report_rows = []
+    duplicate_counts: dict[str, int] = {}
+    clusters_by_group: dict[str, list[DuplicateCluster]] = {}
+
+    for cls in class_folders:
+        print("\n" + "=" * 60)
+        print("Processing:", cls)
+
+        cls_path = os.path.join(dataset_path, cls)
+        image_paths = get_image_paths(cls_path, extensions)
+        print("Total images found:", len(image_paths))
+
+        hashed_images = compute_hashes(image_paths, algo=algo)
+        hashed_by_path = {hi.path: hi for hi in hashed_images}
+
+        clusters = cluster_duplicates(hashed_images, threshold=threshold)
+        clusters_by_group[cls] = clusters
+        duplicated_paths = {p for c in clusters for p in c.duplicates}
+
+        for cluster_id, cluster in enumerate(clusters, start=1):
+            kept_hash = hashed_by_path[cluster.kept].hash
+            for dup_path in cluster.duplicates:
+                dup_hash = hashed_by_path[dup_path].hash
+                report_rows.append({
+                    "Class": cls,
+                    "Cluster ID": f"{cls}-{cluster_id}",
+                    "Original Image": os.path.basename(cluster.kept),
+                    "Duplicate Image": os.path.basename(dup_path),
+                    "Original Hash": str(kept_hash),
+                    "Duplicate Hash": str(dup_hash),
+                    "Hamming Distance": dup_hash - kept_hash,
+                    # kept out of the Excel export, used only for PDF/HTML thumbnails
+                    "_Original Path": cluster.kept,
+                    "_Duplicate Path": dup_path,
+                })
+
+        # Copy every image that is NOT flagged as a duplicate (i.e. every
+        # cluster's kept representative, plus every image with no duplicate at all)
+        kept_count = 0
+        for img_path in image_paths:
+            if img_path in duplicated_paths:
+                continue
+            dst_dir = os.path.join(clean_dataset_path, cls)
+            dst_path = _unique_dst_path(dst_dir, os.path.basename(img_path))
+            try:
+                shutil.copy2(img_path, dst_path)
+                kept_count += 1
+            except Exception as e:
+                print(f"Error copying {img_path}: {e}")
+
+        duplicate_counts[cls] = len(duplicated_paths)
+        print(f"Duplicate groups found: {len(clusters)}  |  Duplicates removed: {len(duplicated_paths)}  |  Images kept: {kept_count}")
+
+    df = pd.DataFrame(report_rows)
+    excel_cols = ["Class", "Cluster ID", "Original Image", "Duplicate Image", "Original Hash", "Duplicate Hash", "Hamming Distance"]
+    summary_rows = [{"Class": cls, "Duplicate Count": c} for cls, c in duplicate_counts.items()]
+    summary_rows.append({"Class": "TOTAL", "Duplicate Count": sum(duplicate_counts.values())})
+    summary_df = pd.DataFrame(summary_rows)
+    matches_df = df[excel_cols] if not df.empty else pd.DataFrame(columns=excel_cols)
+
+    os.makedirs(os.path.dirname(report_path) or ".", exist_ok=True)
+    with pd.ExcelWriter(report_path, engine="openpyxl") as writer:
+        summary_df.to_excel(writer, sheet_name="Duplicate Count", index=False)
+        matches_df.to_excel(writer, sheet_name="Matches", index=False)
+
+    print("\n" + "=" * 60)
+    print("DONE")
+    print("Clean dataset saved at:", clean_dataset_path)
+    print("Duplicate report saved at:", report_path)
+
+    if extra_formats:
+        from .export import export_extra_formats  # imported lazily, no hard dependency beyond pandas
+        export_extra_formats({"summary": summary_df, "matches": matches_df}, report_path, extra_formats)
+
+    if pdf_report_path:
+        from .report import render_pair_report_pdf  # imported lazily: fpdf2 is an optional extra
+        render_pair_report_pdf(
+            rows=report_rows,
+            output_path=pdf_report_path,
+            title="Duplicate Removal Report",
+            group_key="Class",
+            left_label="Kept (original)",
+            left_path_key="_Original Path",
+            right_label="Removed (duplicate)",
+            right_path_key="_Duplicate Path",
+            distance_key="Hamming Distance",
+        )
+        print("Visual PDF report saved at:", pdf_report_path)
+
+    if html_report_path:
+        from .report import render_cluster_report_html
+        render_cluster_report_html(
+            clusters_by_group=clusters_by_group,
+            output_path=html_report_path,
+            title="Duplicate Removal Report",
+        )
+
+    return duplicate_counts
+
+
+def clean_duplicates_inplace(
+    dataset_path: str,
+    report_path: str,
+    threshold: int = 3,
+    algo: str = "phash",
+    extensions=DEFAULT_EXTENSIONS,
+    extra_formats: list[str] | None = None,
+) -> dict:
+    """Remove within-class near-duplicates directly from dataset_path.
+
+    DESTRUCTIVE: deletes duplicate image files from the source dataset.
+    The cluster representative (kept image) is never deleted — only the
+    redundant copies are removed.
+
+    Use clean_duplicates() instead if you want a separate clean copy
+    and wish to preserve the original dataset intact.
+
+    Writes an Excel report with two sheets:
+      - 'Duplicate Count': per-class duplicate counts + TOTAL
+      - 'Removed Images':  every removed duplicate with its kept original
+                           and Hamming distance
+
+    Returns {class_name: duplicate_count}.
+    """
+    if algo not in HASH_ALGORITHMS:
+        raise ValueError(f"Unknown hash algorithm '{algo}'. Choose from {list(HASH_ALGORITHMS)}")
+
+    class_folders = [d for d in os.listdir(dataset_path) if os.path.isdir(os.path.join(dataset_path, d))]
+
+    report_rows = []
+    duplicate_counts: dict[str, int] = {}
+
+    for cls in class_folders:
+        print("\n" + "=" * 60)
+        print("Processing:", cls)
+
+        cls_path = os.path.join(dataset_path, cls)
+        image_paths = get_image_paths(cls_path, extensions)
+        print("Total images found:", len(image_paths))
+
+        hashed_images = compute_hashes(image_paths, algo=algo)
+        hashed_by_path = {hi.path: hi for hi in hashed_images}
+
+        clusters = cluster_duplicates(hashed_images, threshold=threshold)
+        duplicated_paths = {p for c in clusters for p in c.duplicates}
+
+        for cluster_id, cluster in enumerate(clusters, start=1):
+            kept_hash = hashed_by_path[cluster.kept].hash
+            for dup_path in cluster.duplicates:
+                dup_hash = hashed_by_path[dup_path].hash
+                report_rows.append({
+                    "Class": cls,
+                    "Cluster ID": f"{cls}-{cluster_id}",
+                    "Kept Image": os.path.basename(cluster.kept),
+                    "Removed Image": os.path.basename(dup_path),
+                    "Kept Hash": str(kept_hash),
+                    "Removed Hash": str(dup_hash),
+                    "Hamming Distance": dup_hash - kept_hash,
+                })
+                try:
+                    os.remove(dup_path)
+                    print(f"  Removed: {os.path.basename(dup_path)}")
+                except Exception as e:
+                    print(f"  [warn] Could not remove {dup_path}: {e}")
+
+        duplicate_counts[cls] = len(duplicated_paths)
+        print(f"Duplicate groups found: {len(clusters)}  |  Duplicates removed: {len(duplicated_paths)}")
+
+    df = pd.DataFrame(report_rows)
+    excel_cols = ["Class", "Cluster ID", "Kept Image", "Removed Image", "Kept Hash", "Removed Hash", "Hamming Distance"]
+    summary_rows = [{"Class": cls, "Duplicate Count": c} for cls, c in duplicate_counts.items()]
+    summary_rows.append({"Class": "TOTAL", "Duplicate Count": sum(duplicate_counts.values())})
+    summary_df = pd.DataFrame(summary_rows)
+    removed_df = df[excel_cols] if not df.empty else pd.DataFrame(columns=excel_cols)
+
+    os.makedirs(os.path.dirname(report_path) or ".", exist_ok=True)
+    with pd.ExcelWriter(report_path, engine="openpyxl") as writer:
+        summary_df.to_excel(writer, sheet_name="Duplicate Count", index=False)
+        removed_df.to_excel(writer, sheet_name="Removed Images", index=False)
+
+    print("\n" + "=" * 60)
+    print("DONE — duplicates removed in-place from:", dataset_path)
+    print("Report saved at:", report_path)
+
+    if extra_formats:
+        from .export import export_extra_formats
+        export_extra_formats({"summary": summary_df, "removed": removed_df}, report_path, extra_formats)
+
+    return duplicate_counts

imgcheck/cli.py

@@ -0,0 +1,264 @@
+"""Command-line interface for imgcheck.
+
+Detection commands (read-only, generate reports):
+    imgcheck stats         -- dataset health check
+    imgcheck clean         -- find within-class duplicates, copy survivors to new folder
+    imgcheck leakage       -- find train/test leaked images
+    imgcheck cross-label   -- find images mislabelled under two classes
+
+Removal commands (modify or copy data, always generate a removal report):
+    imgcheck clean-inplace   -- delete within-class duplicates in-place
+    imgcheck leakage-fix     -- remove leaked test images (inplace or copy mode)
+    imgcheck cross-label-fix -- remove cross-label duplicates (inplace or copy mode)
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from .clean import clean_duplicates, clean_duplicates_inplace
+from .cross_label import check_cross_label_duplicates
+from .cross_label_fix import fix_cross_label_duplicates
+from .export import SUPPORTED_FORMATS
+from .hashing import HASH_ALGORITHMS
+from .leakage import check_train_test_leakage
+from .leakage_fix import fix_train_test_leakage
+from .stats import compute_dataset_stats
+
+
+def _add_common_hash_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--threshold", type=int, default=3,
+        help="Max Hamming distance to count as a match (0=exact only, 1-3=near-duplicate). Default: 3",
+    )
+    parser.add_argument(
+        "--algo", choices=list(HASH_ALGORITHMS), default="phash",
+        help="Perceptual hash algorithm to use. Default: phash",
+    )
+
+
+def _add_report_output_args(parser: argparse.ArgumentParser, pair_or_cluster: str) -> None:
+    parser.add_argument(
+        "--pdf", default=None,
+        help=f"Optional: also write a visual .pdf report of {pair_or_cluster} (needs fpdf2, pip install imgcheck[pdf])",
+    )
+    parser.add_argument(
+        "--html", default=None,
+        help=f"Optional: also write a self-contained .html gallery of {pair_or_cluster} (no extra dependency)",
+    )
+    parser.add_argument(
+        "--formats", default=None,
+        help=f"Optional: comma-separated extra export formats for the report tables, e.g. csv,json. Choose from {list(SUPPORTED_FORMATS)}",
+    )
+
+
+def _add_fix_mode_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--mode", choices=["inplace", "copy"], default="inplace",
+        help=(
+            "Removal mode. "
+            "'inplace' deletes directly from the source folder (DESTRUCTIVE). "
+            "'copy' creates a new clean folder with only the surviving images. "
+            "Default: inplace"
+        ),
+    )
+    parser.add_argument(
+        "--output", default=None,
+        help="Required when --mode copy. Path for the new clean output folder.",
+    )
+    parser.add_argument(
+        "--formats", default=None,
+        help=f"Optional: comma-separated extra export formats for the removal report, e.g. csv,json. Choose from {list(SUPPORTED_FORMATS)}",
+    )
+
+
+def _parse_formats(raw: str | None) -> list[str] | None:
+    if not raw:
+        return None
+    return [f.strip() for f in raw.split(",") if f.strip()]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="imgcheck",
+        description=(
+            "Perceptual-hash based image dataset auditing and cleaning. "
+            "Detection commands are read-only and generate reports. "
+            "Removal commands (*-fix / *-inplace) modify or copy data."
+        ),
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # ------------------------------------------------------------------ #
+    #  DETECTION COMMANDS                                                  #
+    # ------------------------------------------------------------------ #
+
+    # --- stats ---
+    stats_p = subparsers.add_parser(
+        "stats",
+        help="Fast dataset health check: counts, resolutions, class balance, corrupt files (no hashing)",
+    )
+    stats_p.add_argument("--dataset", required=True, help="Path to dataset root (contains class subfolders)")
+    stats_p.add_argument("--report", default=None, help="Optional output .xlsx report path")
+
+    # --- clean ---
+    clean_p = subparsers.add_parser(
+        "clean",
+        help="Find within-class near-duplicates and copy only survivors to a new clean folder (source untouched)",
+    )
+    clean_p.add_argument("--dataset", required=True, help="Path to source dataset (contains class subfolders)")
+    clean_p.add_argument("--output",  required=True, help="Path to write the cleaned dataset")
+    clean_p.add_argument("--report",  required=True, help="Output .xlsx report path")
+    _add_report_output_args(clean_p, "kept/duplicate pairs")
+    _add_common_hash_args(clean_p)
+
+    # --- leakage ---
+    leak_p = subparsers.add_parser(
+        "leakage",
+        help="Check for train/test leakage between two dataset splits (read-only, report only)",
+    )
+    leak_p.add_argument("--train",  required=True, help="Path to train root (contains class subfolders)")
+    leak_p.add_argument("--test",   required=True, help="Path to test root (contains class subfolders)")
+    leak_p.add_argument("--report", required=True, help="Output .xlsx report path")
+    _add_report_output_args(leak_p, "leaked pairs")
+    _add_common_hash_args(leak_p)
+
+    # --- cross-label ---
+    cross_p = subparsers.add_parser(
+        "cross-label",
+        help="Find images filed under two different class labels (read-only, report only)",
+    )
+    cross_p.add_argument("--dataset", required=True, help="Path to dataset (contains class subfolders)")
+    cross_p.add_argument("--report",  required=True, help="Output .xlsx report path")
+    _add_report_output_args(cross_p, "cross-label pairs")
+    _add_common_hash_args(cross_p)
+
+    # ------------------------------------------------------------------ #
+    #  REMOVAL COMMANDS                                                    #
+    # ------------------------------------------------------------------ #
+
+    # --- clean-inplace ---
+    ci_p = subparsers.add_parser(
+        "clean-inplace",
+        help="Delete within-class near-duplicates directly from the source dataset (DESTRUCTIVE)",
+    )
+    ci_p.add_argument("--dataset", required=True, help="Path to dataset root (contains class subfolders)")
+    ci_p.add_argument("--report",  required=True, help="Output .xlsx removal report path")
+    ci_p.add_argument(
+        "--formats", default=None,
+        help=f"Optional: comma-separated extra export formats, e.g. csv,json. Choose from {list(SUPPORTED_FORMATS)}",
+    )
+    _add_common_hash_args(ci_p)
+
+    # --- leakage-fix ---
+    lf_p = subparsers.add_parser(
+        "leakage-fix",
+        help="Detect and remove leaked test images. Use --mode to choose inplace deletion or copy-to-new-folder.",
+    )
+    lf_p.add_argument("--train",  required=True, help="Path to train root (contains class subfolders)")
+    lf_p.add_argument("--test",   required=True, help="Path to test root (contains class subfolders)")
+    lf_p.add_argument("--report", required=True, help="Output .xlsx removal report path")
+    _add_fix_mode_args(lf_p)
+    _add_common_hash_args(lf_p)
+
+    # --- cross-label-fix ---
+    clf_p = subparsers.add_parser(
+        "cross-label-fix",
+        help="Detect and remove cross-label duplicate images. Use --mode to choose inplace deletion or copy-to-new-folder.",
+    )
+    clf_p.add_argument("--dataset", required=True, help="Path to dataset root (contains class subfolders)")
+    clf_p.add_argument("--report",  required=True, help="Output .xlsx removal report path")
+    _add_fix_mode_args(clf_p)
+    _add_common_hash_args(clf_p)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    # --- detection ---
+    if args.command == "stats":
+        compute_dataset_stats(
+            dataset_root=args.dataset,
+            report_path=args.report,
+        )
+
+    elif args.command == "clean":
+        clean_duplicates(
+            dataset_path=args.dataset,
+            clean_dataset_path=args.output,
+            report_path=args.report,
+            threshold=args.threshold,
+            algo=args.algo,
+            pdf_report_path=args.pdf,
+            html_report_path=args.html,
+            extra_formats=_parse_formats(args.formats),
+        )
+
+    elif args.command == "leakage":
+        check_train_test_leakage(
+            train_root=args.train,
+            test_root=args.test,
+            report_path=args.report,
+            threshold=args.threshold,
+            algo=args.algo,
+            pdf_report_path=args.pdf,
+            html_report_path=args.html,
+            extra_formats=_parse_formats(args.formats),
+        )
+
+    elif args.command == "cross-label":
+        check_cross_label_duplicates(
+            dataset_root=args.dataset,
+            report_path=args.report,
+            threshold=args.threshold,
+            algo=args.algo,
+            pdf_report_path=args.pdf,
+            html_report_path=args.html,
+            extra_formats=_parse_formats(args.formats),
+        )
+
+    # --- removal ---
+    elif args.command == "clean-inplace":
+        clean_duplicates_inplace(
+            dataset_path=args.dataset,
+            report_path=args.report,
+            threshold=args.threshold,
+            algo=args.algo,
+            extra_formats=_parse_formats(args.formats),
+        )
+
+    elif args.command == "leakage-fix":
+        if args.mode == "copy" and not args.output:
+            parser.error("--output is required when --mode is 'copy'")
+        fix_train_test_leakage(
+            train_root=args.train,
+            test_root=args.test,
+            report_path=args.report,
+            mode=args.mode,
+            output_root=args.output,
+            threshold=args.threshold,
+            algo=args.algo,
+            extra_formats=_parse_formats(args.formats),
+        )
+
+    elif args.command == "cross-label-fix":
+        if args.mode == "copy" and not args.output:
+            parser.error("--output is required when --mode is 'copy'")
+        fix_cross_label_duplicates(
+            dataset_root=args.dataset,
+            report_path=args.report,
+            mode=args.mode,
+            output_root=args.output,
+            threshold=args.threshold,
+            algo=args.algo,
+            extra_formats=_parse_formats(args.formats),
+        )
+
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

imgcheck/cross_label.py

@@ -0,0 +1,134 @@
+"""Cross-label duplicate detection.
+
+`clean.py` only looks for duplicates *within* a class folder. But a
+more serious bug is the same (or near-identical) image appearing
+under *two different class labels* — e.g. an MRI scan filed under
+both "glioma" and "meningioma". That's not just wasted storage, it's
+a contradictory training signal. This module hashes every image in
+the dataset together (ignoring class) and flags any pair that's
+within threshold but sits in different class folders.
+"""
+
+from __future__ import annotations
+
+import os
+
+import pandas as pd
+
+from .hashing import DEFAULT_EXTENSIONS, compute_hashes, get_image_paths, hamming_distance
+
+
+def check_cross_label_duplicates(
+    dataset_root: str,
+    report_path: str,
+    threshold: int = 3,
+    algo: str = "phash",
+    extensions=DEFAULT_EXTENSIONS,
+    pdf_report_path: str | None = None,
+    html_report_path: str | None = None,
+    extra_formats: list[str] | None = None,
+) -> list[dict]:
+    """Hash every image under every class subfolder of dataset_root,
+    then flag any pair within threshold that belongs to two *different*
+    classes (same-class matches are not cross-label issues — see
+    clean.py for those).
+
+    Writes an Excel report with two sheets:
+      - "Summary": count of cross-label matches per class pair
+      - "Matches": every flagged pair, with both images, both classes,
+                    and the Hamming distance
+
+    Optional outputs:
+      - pdf_report_path: visual PDF (requires `fpdf2`, pip install imgdedup[pdf])
+      - html_report_path: self-contained HTML gallery of flagged pairs
+      - extra_formats: e.g. ["csv", "json"] — also export the two
+                        report tables in these formats alongside Excel
+
+    Returns the list of matched-pair row dicts.
+    """
+    class_folders = sorted(d for d in os.listdir(dataset_root) if os.path.isdir(os.path.join(dataset_root, d)))
+    if len(class_folders) < 2:
+        raise ValueError("Need at least 2 class subfolders to check for cross-label duplicates")
+
+    all_hashed = []  # list of (HashedImage, class_name)
+    for cls in class_folders:
+        paths = get_image_paths(os.path.join(dataset_root, cls), extensions)
+        for hi in compute_hashes(paths, algo=algo):
+            all_hashed.append((hi, cls))
+
+    print(f"Hashed {len(all_hashed)} images across {len(class_folders)} classes")
+
+    rows = []
+    n = len(all_hashed)
+    for i in range(n):
+        hi_a, cls_a = all_hashed[i]
+        for j in range(i + 1, n):
+            hi_b, cls_b = all_hashed[j]
+            if cls_a == cls_b:
+                continue  # same-class matches belong to clean.py, not here
+            d = hamming_distance(hi_a.hash, hi_b.hash)
+            if d <= threshold:
+                rows.append({
+                    "Class A": cls_a,
+                    "Image A": os.path.basename(hi_a.path),
+                    "Class B": cls_b,
+                    "Image B": os.path.basename(hi_b.path),
+                    "Hamming Distance": d,
+                    "_Image A Path": hi_a.path,
+                    "_Image B Path": hi_b.path,
+                })
+
+    print(f"Cross-label duplicate pairs found: {len(rows)}")
+
+    df = pd.DataFrame(rows)
+    excel_cols = ["Class A", "Image A", "Class B", "Image B", "Hamming Distance"]
+
+    if not df.empty:
+        summary_df = (
+            df.groupby(["Class A", "Class B"]).size().reset_index(name="Match Count").sort_values("Match Count", ascending=False)
+        )
+    else:
+        summary_df = pd.DataFrame(columns=["Class A", "Class B", "Match Count"])
+
+    os.makedirs(os.path.dirname(report_path) or ".", exist_ok=True)
+    with pd.ExcelWriter(report_path, engine="openpyxl") as writer:
+        summary_df.to_excel(writer, sheet_name="Summary", index=False)
+        (df[excel_cols] if not df.empty else df).to_excel(writer, sheet_name="Matches", index=False)
+    print("Report saved to:", report_path)
+
+    matches_export_df = df[excel_cols] if not df.empty else pd.DataFrame(columns=excel_cols)
+
+    if extra_formats:
+        from .export import export_extra_formats
+        export_extra_formats({"summary": summary_df, "matches": matches_export_df}, report_path, extra_formats)
+
+    if pdf_report_path:
+        from .report import render_pair_report_pdf
+        render_pair_report_pdf(
+            rows=rows,
+            output_path=pdf_report_path,
+            title="Cross-Label Duplicate Report",
+            group_key="Class A",
+            left_label="Image (Class A)",
+            left_path_key="_Image A Path",
+            right_label="Image (Class B)",
+            right_path_key="_Image B Path",
+            distance_key="Hamming Distance",
+        )
+        print("Visual PDF report saved at:", pdf_report_path)
+
+    if html_report_path:
+        from .report import render_pair_report_html
+        render_pair_report_html(
+            rows=rows,
+            output_path=html_report_path,
+            title="Cross-Label Duplicate Report",
+            group_key="Class A",
+            left_label="Image (Class A)",
+            left_path_key="_Image A Path",
+            right_label="Image (Class B)",
+            right_path_key="_Image B Path",
+            distance_key="Hamming Distance",
+        )
+
+    return rows