Merge branch 'main' into deploy

.gitignore

@@ -1,6 +1,16 @@
 __pycache__/
 *.pyc
+*.pyo
 .venv/
 .env
 .DS_Store
 .streamlit/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.ipynb_checkpoints/
+*.egg-info/
+build/
+dist/

Makefile

@@ -1,22 +1,48 @@
 PYTHON ?= python3
+UV ?= uv
+PYTHON_VERSION ?= 3.11
 VENV ?= .venv
 PIP := $(VENV)/bin/pip
+PYTEST := $(VENV)/bin/pytest
 STREAMLIT := $(VENV)/bin/streamlit
 
 SPACE ?= amithjkamath/rtssdiffviewer
 HF_REMOTE ?= hf
 DEPLOY_BRANCH ?= deploy
 
-.PHONY: install run fmt lint clean deploy-init deploy status
+.PHONY: check-uv venv install run test test-all fmt lint clean clean-venv clean-py deploy-init deploy deploy-now status
+
+check-uv:
+	@command -v $(UV) >/dev/null 2>&1 || { \
+		echo "uv is required. Install from https://docs.astral.sh/uv/getting-started/installation/"; \
+		exit 1; \
+	}
+
+venv:
+	$(MAKE) check-uv
+	rm -rf $(VENV)
+	$(UV) venv --python $(PYTHON_VERSION) $(VENV)
 
 install:
-	$(PYTHON) -m venv $(VENV)
-	$(PIP) install --upgrade pip
-	$(PIP) install -r requirements.txt
+	$(MAKE) venv
+	$(UV) pip install --python $(VENV)/bin/python -r requirements.txt
+	$(UV) pip install --python $(VENV)/bin/python -e .
 
 run:
 	$(STREAMLIT) run app.py
 
+test:
+	@if [ -x "$(PYTEST)" ]; then \
+		$(PYTEST) -q; \
+	else \
+		echo "pytest is not installed in $(VENV). Run 'make install' first."; \
+		exit 1; \
+	fi
+
+test-all:
+	$(MAKE) install
+	$(MAKE) test
+
 fmt:
 	@echo "No formatter configured."
 
@@ -28,7 +54,16 @@ lint:
 	fi
 
 clean:
-	rm -rf $(VENV) __pycache__ src/rtssdiffviewer/__pycache__
+	$(MAKE) clean-venv
+	$(MAKE) clean-py
+
+clean-venv:
+	rm -rf $(VENV)
+
+clean-py:
+	find . -type d -name "__pycache__" -prune -exec rm -rf {} +
+	find . -type f \( -name "*.pyc" -o -name "*.pyo" \) -delete
+	rm -rf .pytest_cache .mypy_cache .ruff_cache .coverage htmlcov .ipynb_checkpoints
 
 deploy-init:
 	@if git remote | grep -q '^$(HF_REMOTE)$$'; then \
@@ -47,5 +82,11 @@ deploy-init:
 deploy:
 	bash deploy.sh $(SPACE)
 
+deploy-now:
+	$(MAKE) deploy-init
+	@git add -A && git commit -m "Deploy: $(shell date '+%Y-%m-%d %H:%M:%S')" || true
+	@git push $(HF_REMOTE) $(DEPLOY_BRANCH):main
+	@echo "Deployment complete. Space: https://huggingface.co/spaces/$(SPACE)"
+
 status:
 	@echo "Space URL: https://huggingface.co/spaces/$(SPACE)"

README.md

@@ -15,16 +15,62 @@ A standalone Streamlit app for:
 
 - converting RTSS `.dcm` files to JSON
 - downloading normalized JSON outputs
-- visualizing git-like diffs between two RTSS versions
+- visualizing intelligent diffs between two RTSS versions (slice-by-slice for contours)
 - batch-uploading multiple variants and switching any two versions for comparison
+- efficiently handling large RTSS files with many contour points
 
-## Local Setup
+## Component Comparison Modes
+
+The app supports comparing four different components:
+
+- **metadata**: DICOM package-level tags using standard unified text diff (fast)
+- **structures**: ROI structure definitions using text diff
+- **references**: Reference frame sequences using text diff  
+- **contours**: Point-cloud comparison grouped by slice plane (z-coordinate)
+  - Optimized for large files with many contour points (>50)
+  - Two-panel left-right layout for easy visual comparison
+  - Shows points organized by slice rather than full text diff
+  - Clearly marks which ROIs/slices are identical, different, or missing
+  - Much faster and more actionable for clinical workflows
+
+## Contour Comparison Features
+
+When comparing contour data:
+- **Slice-by-slice organization**: Each z-coordinate (slice plane) shown in a collapsible expander
+- **Two-panel layout**: Left file contents on the left, right file contents on the right
+- **Visual indicators**:
+  - ✓ Identical ROI and points
+  - ⚠️ Different points in ROI  
+  - ⊘ ROI only exists in one file
+  - ✅ Entire slice is identical
+  - ❌ No contour data on this slice
+- **Component equality**: When metadata, structures, or references are identical, a clear message indicates no differences
+
+## User Workflows
+
+- `Instructions` mode: in-app overview of Pair Mode and Batch Compare usage.
+- `Pair Mode`: upload two RTSS files, inspect structured diff by component, and view contour points in 3D.
+- `Batch Compare`: upload multiple RTSS files and compare any two using your choice of comparison component.
+
+## Developer Setup
 
 ```bash
 make install
 make run
 ```
 
+## Developer Testing
+
+```bash
+make test
+```
+
+To install dependencies and run tests in one step:
+
+```bash
+make test-all
+```
+
 ## Hugging Face Spaces Deployment
 
 Use the deploy workflow in this repository:

app.py

@@ -5,9 +5,11 @@ from __future__ import annotations
 
 import sys
 import tempfile
+from math import sqrt
 from pathlib import Path
 from typing import Any
 
+import plotly.graph_objects as go
 import streamlit as st
 
 ROOT = Path(__file__).resolve().parent
@@ -19,6 +21,8 @@ from rtssdiffviewer.dcm_to_json import dcm_to_json  # noqa: E402
 from rtssdiffviewer.diff_core import (  # noqa: E402
     COMPONENT_KEYS,
     DEFAULT_VOLATILE_TAG_PREFIXES,
+    contour_diff_text,
+    get_contour_slices_structured,
     normalize_value,
     pretty_json_text,
     select_component,
@@ -47,6 +51,539 @@ def ensure_state() -> None:
     st.session_state.setdefault("left_json_raw", None)
     st.session_state.setdefault("right_json_raw", None)
     st.session_state.setdefault("batch_variants", {})
+    st.session_state.setdefault("pair_step", "Upload Pair")
+    st.session_state.setdefault("pair_diff_requested", False)
+    st.session_state.setdefault("pair_diff_sig", None)
+    st.session_state.setdefault("pair_focus_slice_z", None)
+    st.session_state.setdefault("axial_target_slice_z", None)
+    st.session_state.setdefault("contour_detail_target_slice_z", None)
+
+
+def _point_distance(a: tuple[float, float, float], b: tuple[float, float, float]) -> float:
+    return sqrt((a[0] - b[0]) ** 2 + (a[1] - b[1]) ** 2 + (a[2] - b[2]) ** 2)
+
+
+def _greedy_point_matches(
+    left_points: list[tuple[float, float, float]],
+    right_points: list[tuple[float, float, float]],
+) -> list[tuple[int, int, float]]:
+    if not left_points or not right_points:
+        return []
+
+    candidates: list[tuple[float, int, int]] = []
+    for li, lp in enumerate(left_points):
+        for ri, rp in enumerate(right_points):
+            candidates.append((_point_distance(lp, rp), li, ri))
+    candidates.sort(key=lambda x: x[0])
+
+    used_left: set[int] = set()
+    used_right: set[int] = set()
+    matches: list[tuple[int, int, float]] = []
+    for dist, li, ri in candidates:
+        if li in used_left or ri in used_right:
+            continue
+        used_left.add(li)
+        used_right.add(ri)
+        matches.append((li, ri, dist))
+    return matches
+
+
+def _slice_point_counts(
+    left_rois: dict[str, list[tuple[float, float, float]]],
+    right_rois: dict[str, list[tuple[float, float, float]]],
+) -> tuple[int, int, list[tuple[float, float, float]], list[tuple[float, float, float]]]:
+    left_points = [p for pts in left_rois.values() for p in pts]
+    right_points = [p for pts in right_rois.values() for p in pts]
+    return len(left_points), len(right_points), left_points, right_points
+
+
+def _slice_match_metrics(
+    left_rois: dict[str, list[tuple[float, float, float]]],
+    right_rois: dict[str, list[tuple[float, float, float]]],
+    tolerance_mm: float,
+) -> dict[str, Any]:
+    left_count, right_count, left_points, right_points = _slice_point_counts(left_rois, right_rois)
+    matches = _greedy_point_matches(left_points, right_points)
+    matched_in_tol = sum(1 for _, _, dist in matches if dist <= tolerance_mm)
+    dice = (2.0 * matched_in_tol) / (left_count + right_count) if (left_count + right_count) > 0 else 1.0
+    mismatch_count = left_count + right_count - (2 * matched_in_tol)
+    count_delta = abs(left_count - right_count)
+
+    left_roi_names = set(left_rois.keys())
+    right_roi_names = set(right_rois.keys())
+    all_roi_names = sorted(left_roi_names | right_roi_names)
+    identical_slice = left_roi_names == right_roi_names and all(
+        sorted(left_rois.get(roi, [])) == sorted(right_rois.get(roi, []))
+        for roi in all_roi_names
+    )
+
+    return {
+        "left_count": left_count,
+        "right_count": right_count,
+        "dice": dice,
+        "mismatch_count": mismatch_count,
+        "count_delta": count_delta,
+        "left_roi_names": left_roi_names,
+        "right_roi_names": right_roi_names,
+        "all_roi_names": all_roi_names,
+        "identical_slice": identical_slice,
+    }
+
+
+def _safe_key_fragment(value: str) -> str:
+    out = []
+    for ch in value:
+        out.append(ch if ch.isalnum() else "_")
+    return "".join(out)
+
+
+def _nearest_slice_value(slices: list[float], target: float | None) -> float | None:
+    if not slices:
+        return None
+    if target is None:
+        return slices[0]
+    return min(slices, key=lambda z: (abs(z - target), z))
+
+
+def _step_slice_value(slices: list[float], current: float, step: int) -> float:
+    if not slices:
+        return current
+    try:
+        idx = slices.index(current)
+    except ValueError:
+        idx = 0
+    next_idx = max(0, min(len(slices) - 1, idx + step))
+    return slices[next_idx]
+
+
+def _format_slice_rois_text(rois: dict[str, list[tuple[float, float, float]]], precision: int) -> str:
+    if not rois:
+        return "(no contours on this slice)"
+
+    lines: list[str] = []
+    for roi_name in sorted(rois.keys()):
+        points = rois[roi_name]
+        lines.append(f"{roi_name}: {len(points)} points")
+        for i, (x, y, z) in enumerate(points, start=1):
+            lines.append(f"  {i:03d}: ({x:.{precision}f}, {y:.{precision}f}, {z:.{precision}f})")
+        lines.append("")
+    return "\n".join(lines).strip()
+
+
+def _extract_ordered_contours_by_slice(
+    rtss_json: dict[str, Any],
+    precision: int = 4,
+) -> dict[float, list[dict[str, Any]]]:
+    """Extract ordered contour polylines grouped by axial slice (z)."""
+    slices: dict[float, list[dict[str, Any]]] = {}
+    roi_contour_seq = rtss_json.get("(3006,0039) ROIContourSequence", [])
+    if not isinstance(roi_contour_seq, list):
+        return slices
+
+    for roi_idx, roi_item in enumerate(roi_contour_seq):
+        if not isinstance(roi_item, dict):
+            continue
+
+        roi_number = roi_item.get("(3006,0084) ReferencedROINumber")
+        if roi_number is None:
+            roi_number = roi_idx
+        roi_name = f"ROI {roi_number}"
+
+        contour_seq = roi_item.get("(3006,0040) ContourSequence", [])
+        if not isinstance(contour_seq, list):
+            continue
+
+        for contour_idx, contour_item in enumerate(contour_seq, start=1):
+            if not isinstance(contour_item, dict):
+                continue
+
+            points = _extract_xyz_points(contour_item.get("(3006,0050) ContourData", []))
+            if not points:
+                continue
+
+            z_mean = sum(p[2] for p in points) / len(points)
+            z_key = round(z_mean, precision)
+            contour_number = contour_item.get("(3006,0048) ContourNumber", contour_idx)
+
+            slices.setdefault(z_key, []).append(
+                {
+                    "roi_name": roi_name,
+                    "contour_label": f"{roi_name} | Contour {contour_number}",
+                    "points": points,
+                }
+            )
+
+    return slices
+
+
+def _add_direction_annotation(
+    fig: go.Figure,
+    points: list[tuple[float, float, float]],
+    color: str,
+    text: str,
+) -> None:
+    if len(points) < 2:
+        return
+    x0, y0, _ = points[0]
+    x1, y1, _ = points[1]
+    fig.add_annotation(
+        x=x1,
+        y=y1,
+        ax=x0,
+        ay=y0,
+        xref="x",
+        yref="y",
+        axref="x",
+        ayref="y",
+        showarrow=True,
+        arrowhead=3,
+        arrowsize=1,
+        arrowwidth=1.6,
+        arrowcolor=color,
+        text=text,
+        font={"size": 11, "color": color},
+        align="left",
+        xanchor="left",
+    )
+
+
+def _add_contour_traces_2d(
+    fig: go.Figure,
+    contours: list[dict[str, Any]],
+    side_name: str,
+    line_color: str,
+    line_dash: str,
+) -> None:
+    for idx, contour in enumerate(contours, start=1):
+        points = contour["points"]
+        if not points:
+            continue
+
+        xs = [p[0] for p in points]
+        ys = [p[1] for p in points]
+        point_ids = list(range(1, len(points) + 1))
+        contour_name = contour["contour_label"]
+
+        fig.add_trace(
+            go.Scatter(
+                x=xs,
+                y=ys,
+                mode="lines+markers",
+                line={"width": 2, "color": line_color, "dash": line_dash},
+                marker={"size": 5, "color": line_color},
+                name=f"{side_name}: {contour_name}",
+                legendgroup=f"{side_name}_{idx}",
+                hovertemplate=(
+                    f"{side_name}<br>{contour_name}<br>Point %{{customdata}}"
+                    "<br>x=%{x:.3f}<br>y=%{y:.3f}<extra></extra>"
+                ),
+                customdata=point_ids,
+            )
+        )
+
+        first = points[0]
+        last = points[-1]
+        fig.add_trace(
+            go.Scatter(
+                x=[first[0]],
+                y=[first[1]],
+                mode="markers+text",
+                marker={"size": 11, "color": line_color, "symbol": "star"},
+                text=["Start"],
+                textposition="top center",
+                name=f"{side_name} start",
+                legendgroup=f"{side_name}_{idx}",
+                showlegend=False,
+                hovertemplate=(
+                    f"{side_name}<br>{contour_name}<br>Start point (index 1)"
+                    "<br>x=%{x:.3f}<br>y=%{y:.3f}<extra></extra>"
+                ),
+            )
+        )
+        fig.add_trace(
+            go.Scatter(
+                x=[last[0]],
+                y=[last[1]],
+                mode="markers+text",
+                marker={"size": 10, "color": line_color, "symbol": "x"},
+                text=[f"End ({len(points)})"],
+                textposition="bottom center",
+                name=f"{side_name} end",
+                legendgroup=f"{side_name}_{idx}",
+                showlegend=False,
+                hovertemplate=(
+                    f"{side_name}<br>{contour_name}<br>End point (index {len(points)})"
+                    "<br>x=%{x:.3f}<br>y=%{y:.3f}<extra></extra>"
+                ),
+            )
+        )
+
+        _add_direction_annotation(fig, points, line_color, f"{side_name} direction")
+
+
+def render_axial_contour_view(
+    *,
+    left_name: str,
+    right_name: str,
+    left_raw: dict[str, Any],
+    right_raw: dict[str, Any],
+    precision: int = 4,
+) -> None:
+    left_by_slice = _extract_ordered_contours_by_slice(left_raw, precision=precision)
+    right_by_slice = _extract_ordered_contours_by_slice(right_raw, precision=precision)
+    all_slices = sorted(set(left_by_slice.keys()) | set(right_by_slice.keys()))
+
+    if not all_slices:
+        st.warning("No contour data found in either RTSS file.")
+        return
+
+    summary_left = sum(len(v) for v in left_by_slice.values())
+    summary_right = sum(len(v) for v in right_by_slice.values())
+    only_left = [z for z in all_slices if z in left_by_slice and z not in right_by_slice]
+    only_right = [z for z in all_slices if z in right_by_slice and z not in left_by_slice]
+
+    m1, m2, m3, m4 = st.columns(4)
+    with m1:
+        st.metric(f"{left_name} slices", f"{len(left_by_slice):,}")
+    with m2:
+        st.metric(f"{right_name} slices", f"{len(right_by_slice):,}")
+    with m3:
+        st.metric(f"{left_name} contours", f"{summary_left:,}")
+    with m4:
+        st.metric(f"{right_name} contours", f"{summary_right:,}")
+
+    if only_left or only_right:
+        notes: list[str] = []
+        if only_left:
+            notes.append(f"Slices only in {left_name}: {len(only_left)}")
+        if only_right:
+            notes.append(f"Slices only in {right_name}: {len(only_right)}")
+        st.warning(" | ".join(notes))
+    else:
+        st.success("Both files have contours on the same set of axial slice positions.")
+
+    target_z = st.session_state.axial_target_slice_z
+    if target_z is not None:
+        aligned_target = _nearest_slice_value(all_slices, target_z)
+        if aligned_target is not None:
+            st.session_state.axial_slice_select = aligned_target
+        st.session_state.axial_target_slice_z = None
+    elif st.session_state.get("axial_slice_select") not in all_slices:
+        st.session_state.axial_slice_select = all_slices[0]
+
+    nav_col_1, nav_col_2, nav_col_3 = st.columns(3)
+    with nav_col_1:
+        if st.button("Previous Slice", key="axial_prev_slice"):
+            st.session_state.axial_slice_select = _step_slice_value(
+                all_slices,
+                st.session_state.get("axial_slice_select", all_slices[0]),
+                -1,
+            )
+            st.rerun()
+    with nav_col_2:
+        if st.button("Next Slice", key="axial_next_slice"):
+            st.session_state.axial_slice_select = _step_slice_value(
+                all_slices,
+                st.session_state.get("axial_slice_select", all_slices[0]),
+                1,
+            )
+            st.rerun()
+    with nav_col_3:
+        if st.button("Open Contour Detail View", key="axial_open_contour_detail"):
+            current_z = st.session_state.get("axial_slice_select", all_slices[0])
+            st.session_state.contour_detail_target_slice_z = current_z
+            st.session_state.pair_focus_slice_z = current_z
+            st.session_state.pair_step = "Contour Detail View"
+            st.rerun()
+
+    selected_z = st.select_slider(
+        "Axial slice z (mm)",
+        options=all_slices,
+        format_func=lambda z: f"{z:.{precision}f}",
+        value=st.session_state.get("axial_slice_select", all_slices[0]),
+        key="axial_slice_select",
+    )
+    st.session_state.pair_focus_slice_z = selected_z
+
+    left_contours = left_by_slice.get(selected_z, [])
+    right_contours = right_by_slice.get(selected_z, [])
+
+    left_labels = {c["contour_label"] for c in left_contours}
+    right_labels = {c["contour_label"] for c in right_contours}
+    only_left_contours = sorted(left_labels - right_labels)
+    only_right_contours = sorted(right_labels - left_labels)
+
+    if left_contours and not right_contours:
+        st.error(f"Slice z={selected_z:.{precision}f} is present only in {left_name}.")
+    elif right_contours and not left_contours:
+        st.error(f"Slice z={selected_z:.{precision}f} is present only in {right_name}.")
+    else:
+        st.info(
+            f"Slice z={selected_z:.{precision}f} has contours in both files: "
+            f"{len(left_contours)} vs {len(right_contours)}"
+        )
+
+    if only_left_contours or only_right_contours:
+        mismatch_notes: list[str] = []
+        if only_left_contours:
+            mismatch_notes.append(f"Contours only in {left_name}: {len(only_left_contours)}")
+        if only_right_contours:
+            mismatch_notes.append(f"Contours only in {right_name}: {len(only_right_contours)}")
+        st.warning(" | ".join(mismatch_notes))
+
+    fig = go.Figure()
+    if left_contours:
+        _add_contour_traces_2d(
+            fig,
+            contours=left_contours,
+            side_name=left_name,
+            line_color="#d62728",
+            line_dash="solid",
+        )
+    if right_contours:
+        _add_contour_traces_2d(
+            fig,
+            contours=right_contours,
+            side_name=right_name,
+            line_color="#2ca02c",
+            line_dash="dot",
+        )
+
+    if not fig.data:
+        st.info("No contours to display for this slice.")
+        return
+
+    fig.update_layout(
+        title=f"Axial Contour View at z={selected_z:.{precision}f} mm",
+        xaxis_title="X (mm)",
+        yaxis_title="Y (mm)",
+        xaxis={"fixedrange": False},
+        yaxis={"scaleanchor": "x", "scaleratio": 1, "fixedrange": False},
+        dragmode="zoom",
+        margin={"l": 10, "r": 10, "t": 48, "b": 10},
+        legend={"orientation": "h", "y": 1.02, "x": 0},
+    )
+    st.plotly_chart(
+        fig,
+        use_container_width=True,
+        config={
+            "scrollZoom": True,
+            "displaylogo": False,
+            "modeBarButtonsToAdd": ["zoom2d", "pan2d", "resetScale2d"],
+        },
+    )
+
+    with st.expander("Slice contour details", expanded=False):
+        left_col, right_col = st.columns(2)
+        with left_col:
+            st.markdown(f"**{left_name}**")
+            if not left_contours:
+                st.caption("No contours on this slice.")
+            else:
+                for c in left_contours:
+                    pts = c["points"]
+                    st.write(
+                        f"{c['contour_label']}: {len(pts)} points | "
+                        f"start=({pts[0][0]:.{precision}f}, {pts[0][1]:.{precision}f}) | "
+                        f"end=({pts[-1][0]:.{precision}f}, {pts[-1][1]:.{precision}f})"
+                    )
+
+
+def render_contour_detail_text_view(
+    *,
+    left_name: str,
+    right_name: str,
+    left_raw: dict[str, Any],
+    right_raw: dict[str, Any],
+    precision: int = 4,
+) -> None:
+    left_contours = select_component(left_raw, "contours")
+    right_contours = select_component(right_raw, "contours")
+    left_slices, right_slices = get_contour_slices_structured(left_contours, right_contours, precision=precision)
+    all_slices = sorted(set(left_slices.keys()) | set(right_slices.keys()))
+
+    if not all_slices:
+        st.warning("No contour data found in either file.")
+        return
+
+    target_z = st.session_state.contour_detail_target_slice_z
+    if target_z is not None:
+        aligned_target = _nearest_slice_value(all_slices, target_z)
+        if aligned_target is not None:
+            st.session_state.contour_detail_slice_select = aligned_target
+        st.session_state.contour_detail_target_slice_z = None
+    elif st.session_state.get("contour_detail_slice_select") not in all_slices:
+        st.session_state.contour_detail_slice_select = all_slices[0]
+
+    nav_col_1, nav_col_2, nav_col_3 = st.columns(3)
+    with nav_col_1:
+        if st.button("Previous Slice", key="detail_prev_slice"):
+            st.session_state.contour_detail_slice_select = _step_slice_value(
+                all_slices,
+                st.session_state.get("contour_detail_slice_select", all_slices[0]),
+                -1,
+            )
+            st.rerun()
+    with nav_col_2:
+        if st.button("Next Slice", key="detail_next_slice"):
+            st.session_state.contour_detail_slice_select = _step_slice_value(
+                all_slices,
+                st.session_state.get("contour_detail_slice_select", all_slices[0]),
+                1,
+            )
+            st.rerun()
+    with nav_col_3:
+        if st.button("Back To Visual Comparison", key="detail_back_to_visual"):
+            current_z = st.session_state.get("contour_detail_slice_select", all_slices[0])
+            st.session_state.axial_target_slice_z = current_z
+            st.session_state.pair_focus_slice_z = current_z
+            st.session_state.pair_step = "Pair Diff"
+            st.session_state.pair_component = "contours"
+            st.session_state.pair_diff_requested = True
+            st.session_state.pair_diff_sig = "force"
+            st.rerun()
+
+    selected_z = st.select_slider(
+        "Contour slice z (mm)",
+        options=all_slices,
+        format_func=lambda z: f"{z:.{precision}f}",
+        value=st.session_state.get("contour_detail_slice_select", all_slices[0]),
+        key="contour_detail_slice_select",
+    )
+    st.session_state.pair_focus_slice_z = selected_z
+
+    left_rois = left_slices.get(selected_z, {})
+    right_rois = right_slices.get(selected_z, {})
+
+    st.markdown(f"### Contour Text Comparison At z={selected_z:.{precision}f}")
+    col_1, col_2 = st.columns(2)
+    with col_1:
+        st.markdown(f"**{left_name}**")
+        st.code(_format_slice_rois_text(left_rois, precision), language="text")
+    with col_2:
+        st.markdown(f"**{right_name}**")
+        st.code(_format_slice_rois_text(right_rois, precision), language="text")
+
+    left_text = _format_slice_rois_text(left_rois, precision)
+    right_text = _format_slice_rois_text(right_rois, precision)
+    diff_text = unified_diff_text(left_text, right_text, left_name, right_name)
+    st.markdown("#### Slice Unified Diff")
+    if diff_text.strip():
+        st.code(diff_text, language="diff")
+    else:
+        st.success("No textual differences on this slice.")
+        with right_col:
+            st.markdown(f"**{right_name}**")
+            if not right_contours:
+                st.caption("No contours on this slice.")
+            else:
+                for c in right_contours:
+                    pts = c["points"]
+                    st.write(
+                        f"{c['contour_label']}: {len(pts)} points | "
+                        f"start=({pts[0][0]:.{precision}f}, {pts[0][1]:.{precision}f}) | "
+                        f"end=({pts[-1][0]:.{precision}f}, {pts[-1][1]:.{precision}f})"
+                    )
 
 
 def render_diff_panel(
@@ -58,15 +595,315 @@ def render_diff_panel(
     component: str,
     precision: int,
     keep_volatile: bool,
+    allow_rich_view: bool,
+    max_rich_chars: int,
+    max_rich_lines: int,
     key_prefix: str,
 ) -> None:
     ignore_prefixes: set[str] = set()
     if not keep_volatile:
         ignore_prefixes.update(DEFAULT_VOLATILE_TAG_PREFIXES)
 
+    # Get selected components
     left_selected = select_component(left_raw, component)
     right_selected = select_component(right_raw, component)
 
+    # Check if components are identical
+    if left_selected == right_selected:
+        st.info(f"✅ **{component.capitalize()} components are identical** — no differences to compare.")
+        col1, col2 = st.columns(2)
+        with col1:
+            left_json_text = pretty_json_text(left_selected)
+            st.download_button(
+                "Download left JSON",
+                data=left_json_text,
+                file_name=f"{Path(left_name).stem}.{component}.json",
+                mime="application/json",
+                key=f"{key_prefix}_dl_left",
+            )
+        with col2:
+            right_json_text = pretty_json_text(right_selected)
+            st.download_button(
+                "Download right JSON",
+                data=right_json_text,
+                file_name=f"{Path(right_name).stem}.{component}.json",
+                mime="application/json",
+                key=f"{key_prefix}_dl_right",
+            )
+        return
+
+    # Special handling for contour diffing with two-panel layout
+    if component == "contours":
+        left_slices, right_slices = get_contour_slices_structured(left_selected, right_selected, precision=precision)
+
+        col1, col2, col3 = st.columns(3)
+        with col1:
+            left_json_text = pretty_json_text(left_selected)
+            st.download_button(
+                "Download left JSON",
+                data=left_json_text,
+                file_name=f"{Path(left_name).stem}.{component}.json",
+                mime="application/json",
+                key=f"{key_prefix}_dl_left",
+            )
+        with col2:
+            right_json_text = pretty_json_text(right_selected)
+            st.download_button(
+                "Download right JSON",
+                data=right_json_text,
+                file_name=f"{Path(right_name).stem}.{component}.json",
+                mime="application/json",
+                key=f"{key_prefix}_dl_right",
+            )
+        with col3:
+            diff_text = contour_diff_text(left_selected, right_selected, left_name, right_name, precision=precision)
+            st.download_button(
+                "Download contour diff",
+                data=diff_text,
+                file_name=f"{Path(left_name).stem}__{Path(right_name).stem}.{component}.diff",
+                mime="text/plain",
+                key=f"{key_prefix}_dl_diff",
+            )
+
+        st.markdown("### Contour Diff View (by Slice Plane)")
+        st.caption(
+            "Contour points are compared by slice plane (z-coordinate). "
+            "Left panel shows the first file, right panel shows the second file."
+        )
+
+        if not left_slices and not right_slices:
+            st.warning("No contour data found in either file.")
+            return
+
+        global_tolerance = st.slider(
+            "Correspondence tolerance (mm)",
+            min_value=0.1,
+            max_value=10.0,
+            value=1.0,
+            step=0.1,
+            key=f"{key_prefix}_corr_tol",
+        )
+
+        filter_col_1, filter_col_2, filter_col_3, filter_col_4 = st.columns(4)
+        with filter_col_1:
+            hide_identical_slices = st.checkbox(
+                "Hide identical slices",
+                value=False,
+                key=f"{key_prefix}_hide_identical_slices",
+            )
+        with filter_col_2:
+            max_dice_filter = st.slider(
+                "Max dice to include",
+                min_value=0.0,
+                max_value=1.0,
+                value=1.0,
+                step=0.01,
+                key=f"{key_prefix}_max_dice",
+            )
+        with filter_col_3:
+            min_mismatch_filter = st.number_input(
+                "Min mismatch",
+                min_value=0,
+                value=0,
+                step=1,
+                key=f"{key_prefix}_min_mismatch",
+            )
+        with filter_col_4:
+            sort_mode = st.selectbox(
+                "Sort slices",
+                options=[
+                    "Worst dice first",
+                    "Best dice first",
+                    "Highest mismatch first",
+                    "Slice z ascending",
+                    "Slice z descending",
+                ],
+                index=0,
+                key=f"{key_prefix}_slice_sort",
+            )
+
+        # Build slice metrics first, then filter/sort.
+        all_z_coords = sorted(set(left_slices.keys()) | set(right_slices.keys()))
+        slice_rows: list[dict[str, Any]] = []
+        for z in all_z_coords:
+            left_rois = left_slices.get(z, {})
+            right_rois = right_slices.get(z, {})
+            metrics = _slice_match_metrics(left_rois, right_rois, global_tolerance)
+            slice_rows.append(
+                {
+                    "z": z,
+                    "left_rois": left_rois,
+                    "right_rois": right_rois,
+                    "left_count": metrics["left_count"],
+                    "right_count": metrics["right_count"],
+                    "dice": metrics["dice"],
+                    "mismatch_count": metrics["mismatch_count"],
+                    "count_delta": metrics["count_delta"],
+                    "identical_slice": metrics["identical_slice"],
+                    "left_roi_names": metrics["left_roi_names"],
+                    "right_roi_names": metrics["right_roi_names"],
+                    "all_roi_names": metrics["all_roi_names"],
+                }
+            )
+
+        filtered_rows = [
+            row
+            for row in slice_rows
+            if row["dice"] <= max_dice_filter
+            and row["mismatch_count"] >= min_mismatch_filter
+            and (not hide_identical_slices or not row["identical_slice"])
+        ]
+
+        if sort_mode == "Worst dice first":
+            filtered_rows.sort(key=lambda r: (r["dice"], -r["mismatch_count"], r["z"]))
+        elif sort_mode == "Best dice first":
+            filtered_rows.sort(key=lambda r: (-r["dice"], -r["mismatch_count"], r["z"]))
+        elif sort_mode == "Highest mismatch first":
+            filtered_rows.sort(key=lambda r: (-r["mismatch_count"], r["dice"], r["z"]))
+        elif sort_mode == "Slice z descending":
+            filtered_rows.sort(key=lambda r: r["z"], reverse=True)
+        else:
+            filtered_rows.sort(key=lambda r: r["z"])
+
+        st.caption(
+            f"Showing {len(filtered_rows)} / {len(slice_rows)} slices after filters "
+            f"(tolerance={global_tolerance:.1f} mm)."
+        )
+
+        if not filtered_rows:
+            st.info("No slices match the current filters.")
+            return
+
+        focus_slice = _nearest_slice_value(
+            [float(row["z"]) for row in filtered_rows],
+            st.session_state.pair_focus_slice_z,
+        )
+        if focus_slice is not None:
+            st.caption(f"Focused slice: z={focus_slice:.{precision}f}")
+
+        # Render two-panel layout for each filtered slice
+        for row in filtered_rows:
+            z = row["z"]
+            left_rois = row["left_rois"]
+            right_rois = row["right_rois"]
+            left_count = row["left_count"]
+            right_count = row["right_count"]
+            mismatch_count = row["mismatch_count"]
+            count_delta = row["count_delta"]
+            dice = row["dice"]
+            left_roi_names = row["left_roi_names"]
+            right_roi_names = row["right_roi_names"]
+            all_roi_names = row["all_roi_names"]
+            identical_slice = row["identical_slice"]
+
+            header = (
+                f"Slice z={z:.{precision}f} | L={left_count} R={right_count} "
+                f"| delta={count_delta} | mismatch={mismatch_count} | dice={dice:.3f}"
+            )
+
+            expanded = focus_slice is not None and z == focus_slice
+            with st.expander(header, expanded=expanded):
+                if st.button(
+                    "Open This Slice In 2D Axial View",
+                    key=f"{key_prefix}_open_axial_{_safe_key_fragment(f'{z:.{precision}f}')}",
+                ):
+                    st.session_state.axial_target_slice_z = z
+                    st.session_state.pair_focus_slice_z = z
+                    st.session_state.pair_step = "2D Axial Contour View"
+                    st.rerun()
+
+                if identical_slice:
+                    st.caption("✅ This slice is identical in both files")
+
+                # Two-column layout for this slice
+                left_col, right_col = st.columns(2)
+
+                # LEFT PANEL
+                with left_col:
+                    st.markdown(f"**{left_name}**")
+                    if z not in left_slices:
+                        st.caption("❌ No contour data on this slice")
+                    else:
+                        for roi_name in sorted(left_rois.keys()):
+                            points = sorted(left_rois[roi_name])
+                            is_different = roi_name not in right_rois or sorted(right_rois[roi_name]) != points
+                            marker = "⚠️" if is_different else "✓"
+                            st.markdown(f"{marker} *{roi_name}* ({len(points)} points)")
+                            points_text = "\n".join(
+                                [f"({x:.{precision}f}, {y:.{precision}f}, {z:.{precision}f})" for x, y, z in points]
+                            )
+                            st.code(points_text, language="")
+                        
+                        # Show ROIs that only exist in right
+                        for roi_name in sorted(right_roi_names - left_roi_names):
+                            st.markdown(f"⊘ *{roi_name}* (only in {right_name})")
+
+                # RIGHT PANEL
+                with right_col:
+                    st.markdown(f"**{right_name}**")
+                    if z not in right_slices:
+                        st.caption("❌ No contour data on this slice")
+                    else:
+                        for roi_name in sorted(right_rois.keys()):
+                            points = sorted(right_rois[roi_name])
+                            is_different = roi_name not in left_rois or sorted(left_rois[roi_name]) != points
+                            marker = "⚠️" if is_different else "✓"
+                            st.markdown(f"{marker} *{roi_name}* ({len(points)} points)")
+                            points_text = "\n".join(
+                                [f"({x:.{precision}f}, {y:.{precision}f}, {z:.{precision}f})" for x, y, z in points]
+                            )
+                            st.code(points_text, language="")
+                        
+                        # Show ROIs that only exist in left
+                        for roi_name in sorted(left_roi_names - right_roi_names):
+                            st.markdown(f"⊘ *{roi_name}* (only in {left_name})")
+
+                st.markdown("#### Correspondence Explorer")
+                common_rois = sorted(left_roi_names & right_roi_names)
+                if not common_rois:
+                    st.caption("No common ROIs on this slice to match.")
+                else:
+                    z_key = _safe_key_fragment(f"{z:.{precision}f}")
+                    roi_choice = st.selectbox(
+                        "ROI",
+                        options=common_rois,
+                        key=f"{key_prefix}_roi_{z_key}",
+                    )
+                    left_roi_points = sorted(left_rois.get(roi_choice, []))
+                    right_roi_points = sorted(right_rois.get(roi_choice, []))
+                    roi_matches = _greedy_point_matches(left_roi_points, right_roi_points)
+
+                    if not roi_matches:
+                        st.caption("No points available for correspondence on this ROI.")
+                    else:
+                        option_labels: list[str] = []
+                        default_labels: list[str] = []
+                        for li, ri, dist in roi_matches:
+                            label = (
+                                f"L{li + 1} {left_roi_points[li]} <-> "
+                                f"R{ri + 1} {right_roi_points[ri]} | d={dist:.3f}"
+                            )
+                            option_labels.append(label)
+                            if dist <= global_tolerance:
+                                default_labels.append(label)
+
+                        selected_pairs = st.multiselect(
+                            "Select correspondences",
+                            options=option_labels,
+                            default=default_labels,
+                            key=f"{key_prefix}_corr_{z_key}_{_safe_key_fragment(roi_choice)}",
+                        )
+                        st.caption(
+                            f"Auto-suggested correspondences within tolerance: {len(default_labels)} / {len(roi_matches)}"
+                        )
+                        if selected_pairs:
+                            st.code("\n".join(selected_pairs), language="text")
+                        else:
+                            st.caption("No correspondences selected.")
+
+        return
+
+    # Standard text-based diffing for other components
     left_norm = normalize_value(left_selected, precision, ignore_prefixes)
     right_norm = normalize_value(right_selected, precision, ignore_prefixes)
 
@@ -101,8 +938,23 @@ def render_diff_panel(
             key=f"{key_prefix}_dl_diff",
         )
 
+    use_unified_only, reason = should_use_unified_only(
+        left_text,
+        right_text,
+        allow_rich_view=allow_rich_view,
+        max_rich_chars=max_rich_chars,
+        max_rich_lines=max_rich_lines,
+    )
+
     st.markdown("### Diff View")
-    if diff_viewer is not None:
+    if use_unified_only:
+        if reason:
+            st.caption(reason)
+        if diff_text.strip():
+            st.code(diff_text, language="diff")
+        else:
+            st.success("No differences after normalization and filtering.")
+    elif diff_viewer is not None:
         diff_viewer(left_text, right_text, split_view=True)
     else:
         if diff_text.strip():
@@ -111,60 +963,626 @@ def render_diff_panel(
             st.success("No differences after normalization and filtering.")
 
 
+def should_use_unified_only(
+    left_text: str,
+    right_text: str,
+    *,
+    allow_rich_view: bool,
+    max_rich_chars: int,
+    max_rich_lines: int,
+) -> tuple[bool, str]:
+    if not allow_rich_view:
+        return True, "Showing unified diff text only for this mode."
+
+    total_chars = len(left_text) + len(right_text)
+    total_lines = left_text.count("\n") + right_text.count("\n") + 2
+    if total_chars > max_rich_chars or total_lines > max_rich_lines:
+        return (
+            True,
+            (
+                "Large comparison detected. Showing unified diff text for faster loading. "
+                f"(chars={total_chars:,}, lines={total_lines:,})"
+            ),
+        )
+
+    return False, ""
+
+
+def _extract_xyz_points(value: Any) -> list[tuple[float, float, float]]:
+    points: list[tuple[float, float, float]] = []
+
+    if isinstance(value, list):
+        if len(value) == 3 and all(isinstance(v, (int, float)) for v in value):
+            points.append((float(value[0]), float(value[1]), float(value[2])))
+        else:
+            for item in value:
+                points.extend(_extract_xyz_points(item))
+
+    return points
+
+
+def extract_contour_points(rtss_json: dict[str, Any]) -> list[tuple[float, float, float]]:
+    points: list[tuple[float, float, float]] = []
+
+    def walk(node: Any) -> None:
+        if isinstance(node, dict):
+            for key, value in node.items():
+                if "ContourData" in key:
+                    points.extend(_extract_xyz_points(value))
+                else:
+                    walk(value)
+            return
+
+        if isinstance(node, list):
+            for item in node:
+                walk(item)
+
+    walk(rtss_json)
+    return points
+
+
+def _as_float_list(value: Any, expected_len: int | None = None) -> list[float] | None:
+    if not isinstance(value, list):
+        return None
+    try:
+        out = [float(v) for v in value]
+    except (TypeError, ValueError):
+        return None
+    if expected_len is not None and len(out) != expected_len:
+        return None
+    return out
+
+
+def _as_int(value: Any) -> int | None:
+    if isinstance(value, int):
+        return value
+    try:
+        return int(str(value))
+    except (TypeError, ValueError):
+        return None
+
+
+def _find_first_keyword_value(node: Any, keyword: str) -> Any | None:
+    if isinstance(node, dict):
+        for key, value in node.items():
+            if keyword in key:
+                return value
+            found = _find_first_keyword_value(value, keyword)
+            if found is not None:
+                return found
+    elif isinstance(node, list):
+        for item in node:
+            found = _find_first_keyword_value(item, keyword)
+            if found is not None:
+                return found
+    return None
+
+
+def _vadd(a: tuple[float, float, float], b: tuple[float, float, float]) -> tuple[float, float, float]:
+    return (a[0] + b[0], a[1] + b[1], a[2] + b[2])
+
+
+def _vscale(v: tuple[float, float, float], s: float) -> tuple[float, float, float]:
+    return (v[0] * s, v[1] * s, v[2] * s)
+
+
+def _vnorm(v: tuple[float, float, float]) -> float:
+    return sqrt(v[0] ** 2 + v[1] ** 2 + v[2] ** 2)
+
+
+def _vunit(v: tuple[float, float, float]) -> tuple[float, float, float] | None:
+    n = _vnorm(v)
+    if n == 0:
+        return None
+    return (v[0] / n, v[1] / n, v[2] / n)
+
+
+def _cross(a: tuple[float, float, float], b: tuple[float, float, float]) -> tuple[float, float, float]:
+    return (
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0],
+    )
+
+
+def _bounds_from_points(points: list[tuple[float, float, float]]) -> dict[str, float] | None:
+    if not points:
+        return None
+    xs = [p[0] for p in points]
+    ys = [p[1] for p in points]
+    zs = [p[2] for p in points]
+    return {
+        "x_min": min(xs),
+        "x_max": max(xs),
+        "y_min": min(ys),
+        "y_max": max(ys),
+        "z_min": min(zs),
+        "z_max": max(zs),
+    }
+
+
+def _extract_volume_bounds_from_rtss(rtss_json: dict[str, Any]) -> tuple[dict[str, float] | None, str]:
+    origin_raw = _find_first_keyword_value(rtss_json, "ImagePositionPatient")
+    orient_raw = _find_first_keyword_value(rtss_json, "ImageOrientationPatient")
+    pixel_spacing_raw = _find_first_keyword_value(rtss_json, "PixelSpacing")
+    rows_raw = _find_first_keyword_value(rtss_json, "Rows")
+    cols_raw = _find_first_keyword_value(rtss_json, "Columns")
+    frames_raw = _find_first_keyword_value(rtss_json, "NumberOfFrames")
+    spacing_between_raw = _find_first_keyword_value(rtss_json, "SpacingBetweenSlices")
+    slice_thickness_raw = _find_first_keyword_value(rtss_json, "SliceThickness")
+
+    origin = _as_float_list(origin_raw, expected_len=3)
+    orient = _as_float_list(orient_raw, expected_len=6)
+    pixel_spacing = _as_float_list(pixel_spacing_raw, expected_len=2)
+    rows = _as_int(rows_raw)
+    cols = _as_int(cols_raw)
+    frames = _as_int(frames_raw)
+
+    if frames is None:
+        frames = 1
+
+    slice_spacing = None
+    if spacing_between_raw is not None:
+        try:
+            slice_spacing = float(spacing_between_raw)
+        except (TypeError, ValueError):
+            slice_spacing = None
+    if slice_spacing is None and slice_thickness_raw is not None:
+        try:
+            slice_spacing = float(slice_thickness_raw)
+        except (TypeError, ValueError):
+            slice_spacing = None
+    if slice_spacing is None:
+        slice_spacing = 1.0
+
+    if origin is None or orient is None or pixel_spacing is None or rows is None or cols is None:
+        return (
+            None,
+            "Volume geometry metadata is incomplete in RTSS. Falling back to contour-point bounds.",
+        )
+
+    row_dir = _vunit((orient[0], orient[1], orient[2]))
+    col_dir = _vunit((orient[3], orient[4], orient[5]))
+    if row_dir is None or col_dir is None:
+        return (
+            None,
+            "Image orientation metadata is invalid. Falling back to contour-point bounds.",
+        )
+
+    normal = _vunit(_cross(row_dir, col_dir))
+    if normal is None:
+        return (
+            None,
+            "Unable to derive slice-normal direction from orientation. Falling back to contour-point bounds.",
+        )
+
+    row_spacing, col_spacing = pixel_spacing[0], pixel_spacing[1]
+    row_extent = max(rows - 1, 0) * row_spacing
+    col_extent = max(cols - 1, 0) * col_spacing
+    depth_extent = max(frames - 1, 0) * slice_spacing
+    origin_xyz = (origin[0], origin[1], origin[2])
+
+    corners: list[tuple[float, float, float]] = []
+    for r in (0.0, row_extent):
+        for c in (0.0, col_extent):
+            for d in (0.0, depth_extent):
+                corner = origin_xyz
+                corner = _vadd(corner, _vscale(row_dir, r))
+                corner = _vadd(corner, _vscale(col_dir, c))
+                corner = _vadd(corner, _vscale(normal, d))
+                corners.append(corner)
+
+    bounds = _bounds_from_points(corners)
+    if bounds is None:
+        return (
+            None,
+            "Unable to derive volume bounds from RTSS metadata. Falling back to contour-point bounds.",
+        )
+
+    return bounds, "Volume extents derived from RTSS geometry metadata."
+
+
+def _merge_bounds(a: dict[str, float] | None, b: dict[str, float] | None) -> dict[str, float] | None:
+    if a is None:
+        return b
+    if b is None:
+        return a
+    return {
+        "x_min": min(a["x_min"], b["x_min"]),
+        "x_max": max(a["x_max"], b["x_max"]),
+        "y_min": min(a["y_min"], b["y_min"]),
+        "y_max": max(a["y_max"], b["y_max"]),
+        "z_min": min(a["z_min"], b["z_min"]),
+        "z_max": max(a["z_max"], b["z_max"]),
+    }
+
+
+def _add_bounds_box(fig: go.Figure, bounds: dict[str, float], color: str, name: str) -> None:
+    x0, x1 = bounds["x_min"], bounds["x_max"]
+    y0, y1 = bounds["y_min"], bounds["y_max"]
+    z0, z1 = bounds["z_min"], bounds["z_max"]
+
+    corners = [
+        (x0, y0, z0),
+        (x1, y0, z0),
+        (x1, y1, z0),
+        (x0, y1, z0),
+        (x0, y0, z1),
+        (x1, y0, z1),
+        (x1, y1, z1),
+        (x0, y1, z1),
+    ]
+    edges = [
+        (0, 1),
+        (1, 2),
+        (2, 3),
+        (3, 0),
+        (4, 5),
+        (5, 6),
+        (6, 7),
+        (7, 4),
+        (0, 4),
+        (1, 5),
+        (2, 6),
+        (3, 7),
+    ]
+
+    for idx, (a, b) in enumerate(edges):
+        xa, ya, za = corners[a]
+        xb, yb, zb = corners[b]
+        fig.add_trace(
+            go.Scatter3d(
+                x=[xa, xb],
+                y=[ya, yb],
+                z=[za, zb],
+                mode="lines",
+                line={"width": 2, "color": color},
+                name=name if idx == 0 else name,
+                legendgroup=name,
+                showlegend=(idx == 0),
+                opacity=0.35,
+            )
+        )
+
+
+def _add_axes_markers(fig: go.Figure, bounds: dict[str, float]) -> None:
+    origin = (bounds["x_min"], bounds["y_min"], bounds["z_min"])
+    x_range = max(bounds["x_max"] - bounds["x_min"], 1.0)
+    y_range = max(bounds["y_max"] - bounds["y_min"], 1.0)
+    z_range = max(bounds["z_max"] - bounds["z_min"], 1.0)
+    axis_len = max(x_range, y_range, z_range) * 0.15
+
+    x_end = (origin[0] + axis_len, origin[1], origin[2])
+    y_end = (origin[0], origin[1] + axis_len, origin[2])
+    z_end = (origin[0], origin[1], origin[2] + axis_len)
+
+    fig.add_trace(
+        go.Scatter3d(
+            x=[origin[0], x_end[0]],
+            y=[origin[1], x_end[1]],
+            z=[origin[2], x_end[2]],
+            mode="lines+markers+text",
+            line={"width": 5, "color": "#1f77b4"},
+            marker={"size": [3, 5], "color": "#1f77b4"},
+            text=["", "X+"],
+            textposition="top center",
+            name="X axis",
+        )
+    )
+    fig.add_trace(
+        go.Scatter3d(
+            x=[origin[0], y_end[0]],
+            y=[origin[1], y_end[1]],
+            z=[origin[2], y_end[2]],
+            mode="lines+markers+text",
+            line={"width": 5, "color": "#ff7f0e"},
+            marker={"size": [3, 5], "color": "#ff7f0e"},
+            text=["", "Y+"],
+            textposition="top center",
+            name="Y axis",
+        )
+    )
+    fig.add_trace(
+        go.Scatter3d(
+            x=[origin[0], z_end[0]],
+            y=[origin[1], z_end[1]],
+            z=[origin[2], z_end[2]],
+            mode="lines+markers+text",
+            line={"width": 5, "color": "#2ca02c"},
+            marker={"size": [3, 5], "color": "#2ca02c"},
+            text=["", "Z+"],
+            textposition="top center",
+            name="Z axis",
+        )
+    )
+
+
+def render_contour_point_cloud(
+    *,
+    left_name: str,
+    right_name: str,
+    left_raw: dict[str, Any],
+    right_raw: dict[str, Any],
+) -> None:
+    left_points = extract_contour_points(left_raw)
+    right_points = extract_contour_points(right_raw)
+    left_volume_bounds, left_volume_msg = _extract_volume_bounds_from_rtss(left_raw)
+    right_volume_bounds, right_volume_msg = _extract_volume_bounds_from_rtss(right_raw)
+
+    c1, c2 = st.columns(2)
+    with c1:
+        st.metric(f"{left_name} points", f"{len(left_points):,}")
+    with c2:
+        st.metric(f"{right_name} points", f"{len(right_points):,}")
+
+    if not left_points and not right_points:
+        st.warning("No contour points found in the selected RTSS files.")
+        return
+
+    contour_bounds = _bounds_from_points([*left_points, *right_points])
+    volume_bounds = _merge_bounds(left_volume_bounds, right_volume_bounds)
+    display_bounds = volume_bounds or contour_bounds
+    if display_bounds is None:
+        st.warning("Unable to determine display bounds for the contour plot.")
+        return
+
+    if volume_bounds is not None:
+        st.caption(
+            "Plot extents are aligned to RTSS-derived imaging volume bounds. "
+            f"Left: {left_volume_msg} Right: {right_volume_msg}"
+        )
+    else:
+        st.caption(
+            "Imaging volume bounds were not available in RTSS metadata. "
+            "Using contour-point bounds instead."
+        )
+
+    control_1, control_2, control_3 = st.columns(3)
+    with control_1:
+        show_left = st.checkbox(f"Show {left_name}", value=True, key="pc_show_left")
+    with control_2:
+        show_right = st.checkbox(f"Show {right_name}", value=True, key="pc_show_right")
+    with control_3:
+        point_size = st.slider("Point size", min_value=1, max_value=8, value=3, key="pc_point_size")
+
+    fig = go.Figure()
+
+    if show_left and left_points:
+        lx, ly, lz = zip(*left_points)
+        fig.add_trace(
+            go.Scatter3d(
+                x=lx,
+                y=ly,
+                z=lz,
+                mode="markers",
+                marker={"size": point_size, "color": "red", "opacity": 0.7},
+                name=f"First RTSS: {left_name}",
+            )
+        )
+
+    if show_right and right_points:
+        rx, ry, rz = zip(*right_points)
+        fig.add_trace(
+            go.Scatter3d(
+                x=rx,
+                y=ry,
+                z=rz,
+                mode="markers",
+                marker={"size": point_size, "color": "green", "opacity": 0.7},
+                name=f"Second RTSS: {right_name}",
+            )
+        )
+
+    if not fig.data:
+        st.info("Both point groups are hidden. Turn at least one group back on.")
+        return
+
+    _add_bounds_box(fig, display_bounds, color="#555555", name="Display bounds")
+    _add_axes_markers(fig, display_bounds)
+
+    x_span = max(display_bounds["x_max"] - display_bounds["x_min"], 1.0)
+    y_span = max(display_bounds["y_max"] - display_bounds["y_min"], 1.0)
+    z_span = max(display_bounds["z_max"] - display_bounds["z_min"], 1.0)
+    pad_ratio = 0.03
+    x_pad = x_span * pad_ratio
+    y_pad = y_span * pad_ratio
+    z_pad = z_span * pad_ratio
+
+    fig.update_layout(
+        title="RTSS Contour Point Cloud Diff",
+        scene={
+            "xaxis_title": "X (mm, patient Left +)",
+            "yaxis_title": "Y (mm, patient Posterior +)",
+            "zaxis_title": "Z (mm, patient Superior +)",
+            "xaxis": {"range": [display_bounds["x_min"] - x_pad, display_bounds["x_max"] + x_pad]},
+            "yaxis": {"range": [display_bounds["y_min"] - y_pad, display_bounds["y_max"] + y_pad]},
+            "zaxis": {"range": [display_bounds["z_min"] - z_pad, display_bounds["z_max"] + z_pad]},
+        },
+        margin={"l": 0, "r": 0, "t": 48, "b": 0},
+        legend={"orientation": "h", "y": 1.02, "x": 0},
+    )
+    st.plotly_chart(fig, use_container_width=True)
+    st.caption(
+        "Coordinate system uses DICOM patient coordinates (LPS): X increases toward patient Left, "
+        "Y increases toward Posterior, and Z increases toward Superior. "
+        "Use drag to rotate, scroll to zoom, and legend clicks to show or hide each group."
+    )
+
+
 def main() -> None:
     st.set_page_config(page_title="RTSS Diff Viewer", layout="wide")
     ensure_state()
 
     st.title("RTSS Diff Viewer")
-    st.caption("Upload RTSS .dcm files, convert to JSON, and compare with git-like diffs.")
-
-    with st.sidebar:
-        st.header("Diff Controls")
-        component_options = ["all", "metadata", *COMPONENT_KEYS.keys()]
-        component = st.selectbox("Component", options=component_options, index=0)
-        precision = st.slider("Float precision", min_value=2, max_value=10, value=6)
-        keep_volatile = st.checkbox("Keep volatile UID/time tags", value=False)
+    st.caption("Compare RTSS DICOM files using textual diffs and 2D axial contour overlays.")
 
-    tab_upload, tab_diff, tab_batch = st.tabs(
-        ["1) Upload Pair", "2) Pair Diff", "3) Batch Compare"]
+    app_mode = st.radio(
+        "Mode",
+        options=["Instructions", "Pair Mode", "Batch Compare"],
+        index=0,
+        horizontal=True,
     )
 
-    with tab_upload:
-        left_col, right_col = st.columns(2)
-        with left_col:
-            left_file = st.file_uploader("Left RTSS (.dcm)", type=["dcm"], key="left_pair")
-        with right_col:
-            right_file = st.file_uploader("Right RTSS (.dcm)", type=["dcm"], key="right_pair")
+    if app_mode == "Instructions":
+        st.markdown("### What This App Does")
+        st.write("This app compares RTSS DICOM files using intelligent text diffs and 2D axial contour overlays.")
+
+        st.markdown("### Pair Mode")
+        st.write("Use Pair Mode to compare exactly two RTSS files in detail.")
+        st.write("1. Open Pair Mode.")
+        st.write("2. In Upload Pair, upload the first and second RTSS .dcm files.")
+        st.write("3. Click Convert pair.")
+        st.write("4. Open Pair Diff to review JSON differences by component:")
+        st.write("   - **metadata**: DICOM package-level tags (fast text diff)")
+        st.write("   - **structures**: ROI structure definitions (text diff)")
+        st.write("   - **references**: Reference frame sequences (text diff)")
+        st.write("   - **contours**: 2D axial visual comparison directly in Pair Diff (fast, slice-by-slice)")
+        st.write("5. Open Contour Detail View to inspect textual point lists and per-slice unified diffs.")
+        st.write("6. Navigation buttons keep the selected slice synchronized between visual and detail views.")
+
+        st.markdown("### Batch Compare")
+        st.write("Use Batch Compare to compare any two files from a larger uploaded set.")
+        st.write("1. Open Batch Compare.")
+        st.write("2. Upload multiple RTSS .dcm files.")
+        st.write("3. Click Convert uploaded set.")
+        st.write("4. Pick any two variants from the dropdowns.")
+        st.write("5. Select the component to compare (see above for component descriptions).")
+        st.write("6. Review the diff and download outputs if needed.")
+
+        st.markdown("### Component Comparison Details")
+        st.write("**Metadata, Structures, References**: Uses standard unified text diff (fast and simple).")
+        st.write("**Contours**: Uses intelligent slice-plane comparison:")
+        st.write("- Contour points are grouped by slice (z-coordinate)")
+        st.write("- For each slice, differences between ROIs are clearly highlighted")
+        st.write("- Slices-only in one file are clearly marked")
+        st.write("- This approach is much faster and more useful for large RTSS files with hundreds of points")
+
+        st.markdown("### Tips")
+        st.write("- For RTSS files with many contour points (>50), use the **contours** component in Pair Diff for fast visual review.")
+        st.write("- For metadata changes, use **metadata** to quickly identify DICOM tag differences.")
+        st.write("- In contour visual view, use slider and Previous/Next buttons to move quickly between slices.")
+        st.write("- Large comparisons automatically switch to unified text diff for faster loading (when not using contour mode).")
+
+    elif app_mode == "Pair Mode":
+        st.markdown("### Pair Mode")
+        step_options = ["Upload Pair", "Pair Diff", "Contour Detail View"]
+        step = st.radio(
+            "Step",
+            options=step_options,
+            index=step_options.index(st.session_state.pair_step),
+            horizontal=True,
+        )
+        st.session_state.pair_step = step
+
+        if step == "Upload Pair":
+            st.info("Step 1 of 3: Upload two RTSS files and click Convert pair.")
+            left_col, right_col = st.columns(2)
+            with left_col:
+                left_file = st.file_uploader("Left RTSS (.dcm)", type=["dcm"], key="left_pair")
+            with right_col:
+                right_file = st.file_uploader("Right RTSS (.dcm)", type=["dcm"], key="right_pair")
+
+            if st.button("Convert pair", type="primary"):
+                if left_file is None or right_file is None:
+                    st.warning("Upload both files first.")
+                else:
+                    with st.spinner("Converting files..."):
+                        st.session_state.left_json_raw = dcm_bytes_to_json_dict(left_file.getvalue())
+                        st.session_state.right_json_raw = dcm_bytes_to_json_dict(right_file.getvalue())
+                        st.session_state.left_name = left_file.name
+                        st.session_state.right_name = right_file.name
+                    st.session_state.pair_diff_requested = False
+                    st.session_state.pair_diff_sig = None
+                    st.session_state.pair_step = "Pair Diff"
+                    st.rerun()
 
-        if st.button("Convert pair", type="primary"):
-            if left_file is None or right_file is None:
-                st.warning("Upload both files first.")
+        elif step == "Pair Diff":
+            st.info("Step 2 of 3: Choose component and compute diff on demand.")
+            st.markdown("**Select what to compare:**")
+            st.caption("**metadata** compares package-level DICOM tags. **structures** and **references** use text diff. **contours** shows an intelligent slice-by-slice point comparison (recommended for large files).")
+            component_options = ["metadata", "structures", "references", "contours"]
+            control_col_1, control_col_2, control_col_3 = st.columns(3)
+            with control_col_1:
+                component = st.selectbox("Component", options=component_options, index=0, key="pair_component")
+            with control_col_2:
+                precision = st.slider("Float precision", min_value=2, max_value=10, value=6, key="pair_precision")
+            with control_col_3:
+                keep_volatile = st.checkbox("Keep volatile UID/time tags", value=False, key="pair_keep_volatile")
+
+            left_raw = st.session_state.left_json_raw
+            right_raw = st.session_state.right_json_raw
+            if left_raw is None or right_raw is None:
+                st.info("Convert a pair in Upload Pair first.")
             else:
-                with st.spinner("Converting files..."):
-                    st.session_state.left_json_raw = dcm_bytes_to_json_dict(left_file.getvalue())
-                    st.session_state.right_json_raw = dcm_bytes_to_json_dict(right_file.getvalue())
-                    st.session_state.left_name = left_file.name
-                    st.session_state.right_name = right_file.name
-                st.success("Pair conversion complete.")
-
-    with tab_diff:
-        left_raw = st.session_state.left_json_raw
-        right_raw = st.session_state.right_json_raw
-        if left_raw is None or right_raw is None:
-            st.info("Convert a pair in tab 1 first.")
+                current_sig = (
+                    component,
+                    precision,
+                    keep_volatile,
+                    st.session_state.left_name,
+                    st.session_state.right_name,
+                )
+                compute_clicked = st.button("Compute Pair Diff", type="primary", key="pair_compute_diff")
+                if compute_clicked:
+                    st.session_state.pair_diff_requested = True
+                    st.session_state.pair_diff_sig = current_sig
+
+                pair_diff_sig = st.session_state.pair_diff_sig
+                should_render_diff = (
+                    st.session_state.pair_diff_requested
+                    and (pair_diff_sig == current_sig or pair_diff_sig == "force")
+                )
+
+                if should_render_diff:
+                    if component == "contours":
+                        st.caption("Visual contour comparison is shown directly for faster slice-by-slice review.")
+                        render_axial_contour_view(
+                            left_name=st.session_state.left_name,
+                            right_name=st.session_state.right_name,
+                            left_raw=left_raw,
+                            right_raw=right_raw,
+                            precision=precision,
+                        )
+                    else:
+                        with st.spinner("Computing diff..."):
+                            render_diff_panel(
+                                left_name=st.session_state.left_name,
+                                right_name=st.session_state.right_name,
+                                left_raw=left_raw,
+                                right_raw=right_raw,
+                                component=component,
+                                precision=precision,
+                                keep_volatile=keep_volatile,
+                                allow_rich_view=True,
+                                max_rich_chars=400_000,
+                                max_rich_lines=5_000,
+                                key_prefix="pair",
+                            )
+                    st.session_state.pair_diff_sig = current_sig
+                else:
+                    st.caption("Diff is computed on demand. Click 'Compute Pair Diff' to run comparison.")
+
         else:
-            render_diff_panel(
-                left_name=st.session_state.left_name,
-                right_name=st.session_state.right_name,
-                left_raw=left_raw,
-                right_raw=right_raw,
-                component=component,
-                precision=precision,
-                keep_volatile=keep_volatile,
-                key_prefix="pair",
-            )
-
-    with tab_batch:
+            st.markdown("### Contour Detail View")
+            st.info(
+                "Step 3 of 3: Inspect textual contour point descriptions on each slice. "
+                "Use this for detailed text-level slice comparison."
+            )
+            left_raw = st.session_state.left_json_raw
+            right_raw = st.session_state.right_json_raw
+            if left_raw is None or right_raw is None:
+                st.info("Convert a pair in Upload Pair first.")
+            else:
+                with st.spinner("Preparing contour slice text comparison..."):
+                    render_contour_detail_text_view(
+                        left_name=st.session_state.left_name,
+                        right_name=st.session_state.right_name,
+                        left_raw=left_raw,
+                        right_raw=right_raw,
+                        precision=4,
+                    )
+
+    else:
+        st.markdown("### Batch Compare")
         files = st.file_uploader(
             "Upload RTSS variant set (.dcm)",
             type=["dcm"],
@@ -189,32 +1607,44 @@ def main() -> None:
         variants = st.session_state.batch_variants
         if not variants:
             st.info("No batch set loaded yet.")
-            return
+        else:
+            names = sorted(variants.keys())
+            if len(names) < 2:
+                st.warning("Need at least two variants.")
+            else:
+                st.markdown("**Select what to compare:**")
+                st.caption("**metadata** compares package-level DICOM tags. **structures** and **references** use text diff. **contours** shows an intelligent slice-by-slice point comparison (recommended for large files).")
+                component_options = ["metadata", "structures", "references", "contours"]
+                control_col_1, control_col_2, control_col_3 = st.columns(3)
+                with control_col_1:
+                    component = st.selectbox("Component", options=component_options, index=0, key="batch_component")
+                with control_col_2:
+                    precision = st.slider("Float precision", min_value=2, max_value=10, value=6, key="batch_precision")
+                with control_col_3:
+                    keep_volatile = st.checkbox("Keep volatile UID/time tags", value=False, key="batch_keep_volatile")
 
-        names = sorted(variants.keys())
-        if len(names) < 2:
-            st.warning("Need at least two variants.")
-            return
+                left_col, right_col = st.columns(2)
+                with left_col:
+                    left_name = st.selectbox("Left variant", names, index=0, key="batch_left")
+                with right_col:
+                    right_name = st.selectbox("Right variant", names, index=1, key="batch_right")
 
-        left_col, right_col = st.columns(2)
-        with left_col:
-            left_name = st.selectbox("Left variant", names, index=0, key="batch_left")
-        with right_col:
-            right_name = st.selectbox("Right variant", names, index=1, key="batch_right")
-
-        if left_name == right_name:
-            st.warning("Select two different variants.")
-        else:
-            render_diff_panel(
-                left_name=left_name,
-                right_name=right_name,
-                left_raw=variants[left_name],
-                right_raw=variants[right_name],
-                component=component,
-                precision=precision,
-                keep_volatile=keep_volatile,
-                key_prefix="batch",
-            )
+                if left_name == right_name:
+                    st.warning("Select two different variants.")
+                else:
+                    render_diff_panel(
+                        left_name=left_name,
+                        right_name=right_name,
+                        left_raw=variants[left_name],
+                        right_raw=variants[right_name],
+                        component=component,
+                        precision=precision,
+                        keep_volatile=keep_volatile,
+                        allow_rich_view=False,
+                        max_rich_chars=0,
+                        max_rich_lines=0,
+                        key_prefix="batch",
+                    )
 
 
 if __name__ == "__main__":

pyproject.toml

@@ -7,6 +7,8 @@ dependencies = [
   "streamlit>=1.43",
   "st-diff-viewer>=1.0.7",
   "pydicom>=3.0.1",
+  "plotly>=5.24",
+  "pytest>=8.3",
 ]
 
 [build-system]

requirements.txt

@@ -1,3 +1,5 @@
 streamlit>=1.43
 st-diff-viewer>=1.0.7
 pydicom>=3.0.1
+plotly>=5.24
+pytest>=8.3

src/rtssdiffviewer/diff_core.py

@@ -81,3 +81,178 @@ def unified_diff_text(left_text: str, right_text: str, left_name: str, right_nam
         lineterm="",
     )
     return "\n".join(diff)
+
+
+def _extract_xyz_points(value: Any) -> list[tuple[float, float, float]]:
+    """Recursively extract (x, y, z) coordinate tuples from nested structures."""
+    points: list[tuple[float, float, float]] = []
+
+    if isinstance(value, list):
+        if len(value) == 3 and all(isinstance(v, (int, float)) for v in value):
+            points.append((float(value[0]), float(value[1]), float(value[2])))
+        else:
+            for item in value:
+                points.extend(_extract_xyz_points(item))
+
+    return points
+
+
+def extract_contours_by_slice(
+    contour_data: dict[str, Any], precision: int
+) -> dict[float, dict[str, list[tuple[float, float, float]]]]:
+    """
+    Extract contours grouped by slice (z-coordinate, rounded to precision).
+    
+    Returns a dict mapping z-coordinate -> {roi_name -> list of (x, y, z) points}
+    """
+    slices: dict[float, dict[str, list[tuple[float, float, float]]]] = {}
+
+    roi_contour_seq = contour_data.get("(3006,0039) ROIContourSequence", [])
+    if not isinstance(roi_contour_seq, list):
+        return slices
+
+    for roi_idx, roi_item in enumerate(roi_contour_seq):
+        if not isinstance(roi_item, dict):
+            continue
+
+        # Try to get ROI identifier - use ReferencedROINumber if available, otherwise use index
+        roi_number = roi_item.get("(3006,0084) ReferencedROINumber")
+        if roi_number is None:
+            roi_number = roi_idx
+        roi_name = f"ROI {roi_number}"
+
+        # Extract contour sequences
+        contour_seq = roi_item.get("(3006,0040) ContourSequence", [])
+        if not isinstance(contour_seq, list):
+            continue
+
+        for contour_item in contour_seq:
+            if not isinstance(contour_item, dict):
+                continue
+
+            points = _extract_xyz_points(contour_item.get("(3006,0050) ContourData", []))
+            if not points:
+                continue
+
+            # Group by z-coordinate (rounded to precision)
+            for x, y, z in points:
+                z_rounded = round(z, precision)
+                if z_rounded not in slices:
+                    slices[z_rounded] = {}
+                if roi_name not in slices[z_rounded]:
+                    slices[z_rounded][roi_name] = []
+                slices[z_rounded][roi_name].append((x, y, z))
+
+    return slices
+
+
+def _format_points_for_display(points: list[tuple[float, float, float]], precision: int = 4) -> str:
+    """Format a list of points as a readable string."""
+    if not points:
+        return "  (no points)"
+    lines = []
+    for i, (x, y, z) in enumerate(sorted(points), 1):
+        lines.append(f"Point {i}: x={x:.{precision}f}, y={y:.{precision}f}, z={z:.{precision}f}")
+    return "\n".join(lines)
+
+
+def get_contour_slices_structured(
+    left_data: dict[str, Any],
+    right_data: dict[str, Any],
+    precision: int = 4,
+) -> tuple[dict[float, dict[str, list[tuple[float, float, float]]]], dict[float, dict[str, list[tuple[float, float, float]]]]]:
+    """
+    Extract and return structured slice data for both left and right files.
+    
+    Returns: (left_slices, right_slices) where each is a dict mapping
+    z-coordinate -> {roi_name -> list of (x, y, z) points}
+    """
+    left_slices = extract_contours_by_slice(left_data, precision)
+    right_slices = extract_contours_by_slice(right_data, precision)
+    return left_slices, right_slices
+
+
+def contour_diff_text(
+    left_data: dict[str, Any],
+    right_data: dict[str, Any],
+    left_name: str,
+    right_name: str,
+    precision: int = 4,
+) -> str:
+    """
+    Generate an intelligent diff for contour data grouped by slice plane.
+    
+    Compares contours by slice (z-coordinate) and shows:
+    - Slices only in left file
+    - Slices only in right file  
+    - Slices in both with point differences
+    """
+    left_slices = extract_contours_by_slice(left_data, precision)
+    right_slices = extract_contours_by_slice(right_data, precision)
+
+    if not left_slices and not right_slices:
+        return "No contour data found in either file."
+
+    lines: list[str] = []
+    lines.append(f"=== Contour Diff by Slice Plane ===")
+    lines.append(f"Left:  {left_name}")
+    lines.append(f"Right: {right_name}")
+    lines.append("")
+
+    all_z_coords = sorted(set(left_slices.keys()) | set(right_slices.keys()))
+
+    for z in all_z_coords:
+        lines.append(f"--- Slice z={z:.{precision}f} ---")
+
+        left_rois = left_slices.get(z, {})
+        right_rois = right_slices.get(z, {})
+
+        if z not in left_slices:
+            lines.append(f"Only in {right_name}:")
+            for roi_name, points in right_rois.items():
+                lines.append(f"  ROI: {roi_name} ({len(points)} points)")
+                lines.append(_format_points_for_display(points, precision))
+            lines.append("")
+            continue
+
+        if z not in right_slices:
+            lines.append(f"Only in {left_name}:")
+            for roi_name, points in left_rois.items():
+                lines.append(f"  ROI: {roi_name} ({len(points)} points)")
+                lines.append(_format_points_for_display(points, precision))
+            lines.append("")
+            continue
+
+        # Both have this slice - compare ROIs
+        all_roi_names = sorted(set(left_rois.keys()) | set(right_rois.keys()))
+        has_differences = False
+
+        for roi_name in all_roi_names:
+            left_points = sorted(left_rois.get(roi_name, []))
+            right_points = sorted(right_rois.get(roi_name, []))
+
+            if left_points == right_points:
+                continue
+
+            has_differences = True
+            lines.append(f"  ROI: {roi_name}")
+
+            if roi_name not in left_rois:
+                lines.append(f"    Only in {right_name}: {len(right_points)} points")
+                lines.append(_format_points_for_display(right_points, precision))
+            elif roi_name not in right_rois:
+                lines.append(f"    Only in {left_name}: {len(left_points)} points")
+                lines.append(_format_points_for_display(left_points, precision))
+            else:
+                lines.append(f"    {left_name}: {len(left_points)} points")
+                lines.append(_format_points_for_display(left_points, precision))
+                lines.append(f"    {right_name}: {len(right_points)} points")
+                lines.append(_format_points_for_display(right_points, precision))
+
+        if has_differences:
+            lines.append("")
+        else:
+            lines.append(f"  All ROIs identical on this slice")
+            lines.append("")
+
+    return "\n".join(lines)

tests/test_app_features.py

@@ -0,0 +1,298 @@
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from app import (
+    _format_slice_rois_text,
+    _greedy_point_matches,
+    _extract_ordered_contours_by_slice,
+    _extract_volume_bounds_from_rtss,
+    _merge_bounds,
+    _nearest_slice_value,
+    _safe_key_fragment,
+    _slice_match_metrics,
+    _step_slice_value,
+    extract_contour_points,
+    should_use_unified_only,
+)
+
+
+def test_extract_contour_points_collects_all_triplets() -> None:
+    sample = {
+        "(3006,0039) ROIContourSequence": [
+            {
+                "(3006,0040) ContourSequence": [
+                    {
+                        "(3006,0050) ContourData": [
+                            [1.0, 2.0, 3.0],
+                            [4, 5, 6],
+                        ]
+                    },
+                    {
+                        "(3006,0050) ContourData": [
+                            [7.5, 8.5, 9.5],
+                        ]
+                    },
+                ]
+            }
+        ]
+    }
+
+    points = extract_contour_points(sample)
+
+    assert points == [
+        (1.0, 2.0, 3.0),
+        (4.0, 5.0, 6.0),
+        (7.5, 8.5, 9.5),
+    ]
+
+
+def test_extract_contour_points_ignores_non_triplet_data() -> None:
+    sample = {
+        "(3006,0050) ContourData": [
+            [1.0, 2.0],
+            [3.0, 4.0, 5.0, 6.0],
+            "not-a-point",
+            {"unexpected": "shape"},
+        ]
+    }
+
+    points = extract_contour_points(sample)
+
+    assert points == []
+
+
+def test_should_use_unified_only_for_batch_text_mode() -> None:
+    use_unified_only, reason = should_use_unified_only(
+        "left",
+        "right",
+        allow_rich_view=False,
+        max_rich_chars=400_000,
+        max_rich_lines=5_000,
+    )
+
+    assert use_unified_only is True
+    assert "unified diff text only" in reason
+
+
+def test_should_use_unified_only_for_large_input() -> None:
+    left = "a" * 250_000
+    right = "b" * 250_000
+
+    use_unified_only, reason = should_use_unified_only(
+        left,
+        right,
+        allow_rich_view=True,
+        max_rich_chars=400_000,
+        max_rich_lines=5_000,
+    )
+
+    assert use_unified_only is True
+    assert "Large comparison detected" in reason
+
+
+def test_should_use_rich_view_for_small_input() -> None:
+    use_unified_only, reason = should_use_unified_only(
+        "small-left\n",
+        "small-right\n",
+        allow_rich_view=True,
+        max_rich_chars=400_000,
+        max_rich_lines=5_000,
+    )
+
+    assert use_unified_only is False
+    assert reason == ""
+
+
+def test_extract_volume_bounds_from_rtss_metadata() -> None:
+    sample = {
+        "(3006,0039) ROIContourSequence": [
+            {
+                "(3006,004A) SourcePixelPlanesCharacteristicsSequence": [
+                    {
+                        "(0020,0032) ImagePositionPatient": [10.0, 20.0, 30.0],
+                        "(0020,0037) ImageOrientationPatient": [1.0, 0.0, 0.0, 0.0, 1.0, 0.0],
+                        "(0028,0030) PixelSpacing": [2.0, 1.0],
+                        "(0028,0010) Rows": 2,
+                        "(0028,0011) Columns": 3,
+                        "(0028,0008) NumberOfFrames": 4,
+                        "(0018,0088) SpacingBetweenSlices": 2.0,
+                    }
+                ]
+            }
+        ]
+    }
+
+    bounds, msg = _extract_volume_bounds_from_rtss(sample)
+
+    assert bounds is not None
+    assert bounds["x_min"] == 10.0
+    assert bounds["x_max"] == 12.0
+    assert bounds["y_min"] == 20.0
+    assert bounds["y_max"] == 22.0
+    assert bounds["z_min"] == 30.0
+    assert bounds["z_max"] == 36.0
+    assert "derived" in msg
+
+
+def test_extract_volume_bounds_from_rtss_missing_metadata() -> None:
+    sample = {
+        "(3006,0039) ROIContourSequence": [
+            {"(3006,0040) ContourSequence": [{"(3006,0050) ContourData": [[1.0, 2.0, 3.0]]}]}
+        ]
+    }
+
+    bounds, msg = _extract_volume_bounds_from_rtss(sample)
+
+    assert bounds is None
+    assert "incomplete" in msg
+
+
+def test_merge_bounds() -> None:
+    a = {"x_min": 0.0, "x_max": 1.0, "y_min": 2.0, "y_max": 3.0, "z_min": 4.0, "z_max": 5.0}
+    b = {"x_min": -1.0, "x_max": 2.0, "y_min": 1.5, "y_max": 3.5, "z_min": 3.0, "z_max": 6.0}
+
+    merged = _merge_bounds(a, b)
+
+    assert merged == {
+        "x_min": -1.0,
+        "x_max": 2.0,
+        "y_min": 1.5,
+        "y_max": 3.5,
+        "z_min": 3.0,
+        "z_max": 6.0,
+    }
+
+
+def test_greedy_point_matches_unique_pairs() -> None:
+    left = [(0.0, 0.0, 0.0), (10.0, 0.0, 0.0)]
+    right = [(0.2, 0.0, 0.0), (9.8, 0.0, 0.0)]
+
+    matches = _greedy_point_matches(left, right)
+
+    assert len(matches) == 2
+    assert {m[0] for m in matches} == {0, 1}
+    assert {m[1] for m in matches} == {0, 1}
+
+
+def test_slice_match_metrics_dice_and_mismatch() -> None:
+    left_rois = {
+        "ROI 1": [
+            (0.0, 0.0, 1.0),
+            (10.0, 0.0, 1.0),
+        ]
+    }
+    right_rois = {
+        "ROI 1": [
+            (0.2, 0.0, 1.0),
+            (11.5, 0.0, 1.0),
+        ]
+    }
+
+    metrics = _slice_match_metrics(left_rois, right_rois, tolerance_mm=1.0)
+
+    assert metrics["left_count"] == 2
+    assert metrics["right_count"] == 2
+    assert metrics["mismatch_count"] == 2
+    assert metrics["count_delta"] == 0
+    assert metrics["dice"] == 0.5
+    assert metrics["identical_slice"] is False
+
+
+def test_slice_match_metrics_identical_slice() -> None:
+    rois = {
+        "ROI 1": [
+            (1.0, 2.0, 3.0),
+            (4.0, 5.0, 3.0),
+        ]
+    }
+
+    metrics = _slice_match_metrics(rois, rois, tolerance_mm=0.1)
+
+    assert metrics["identical_slice"] is True
+    assert metrics["mismatch_count"] == 0
+    assert metrics["dice"] == 1.0
+
+
+def test_safe_key_fragment_replaces_non_alnum() -> None:
+    assert _safe_key_fragment("z=12.5/ROI 1") == "z_12_5_ROI_1"
+
+
+def test_nearest_slice_value_selects_closest() -> None:
+    slices = [1.0, 2.5, 5.0]
+
+    assert _nearest_slice_value(slices, 2.7) == 2.5
+    assert _nearest_slice_value(slices, None) == 1.0
+
+
+def test_nearest_slice_value_returns_none_for_empty() -> None:
+    assert _nearest_slice_value([], 10.0) is None
+
+
+def test_extract_ordered_contours_by_slice_preserves_point_order() -> None:
+    sample = {
+        "(3006,0039) ROIContourSequence": [
+            {
+                "(3006,0084) ReferencedROINumber": 7,
+                "(3006,0040) ContourSequence": [
+                    {
+                        "(3006,0048) ContourNumber": 3,
+                        "(3006,0050) ContourData": [
+                            [10.0, 5.0, 1.0001],
+                            [11.0, 6.0, 1.0001],
+                            [12.0, 7.0, 1.0001],
+                        ],
+                    }
+                ],
+            }
+        ]
+    }
+
+    slices = _extract_ordered_contours_by_slice(sample, precision=3)
+
+    assert list(slices.keys()) == [1.0]
+    assert len(slices[1.0]) == 1
+    contour = slices[1.0][0]
+    assert contour["contour_label"] == "ROI 7 | Contour 3"
+    assert contour["points"] == [
+        (10.0, 5.0, 1.0001),
+        (11.0, 6.0, 1.0001),
+        (12.0, 7.0, 1.0001),
+    ]
+
+
+def test_step_slice_value_bounds_and_steps() -> None:
+    slices = [1.0, 2.0, 3.0]
+
+    assert _step_slice_value(slices, 2.0, -1) == 1.0
+    assert _step_slice_value(slices, 2.0, 1) == 3.0
+    assert _step_slice_value(slices, 1.0, -1) == 1.0
+    assert _step_slice_value(slices, 3.0, 1) == 3.0
+
+
+def test_step_slice_value_handles_missing_current() -> None:
+    slices = [1.0, 2.0, 3.0]
+    assert _step_slice_value(slices, 99.0, 1) == 2.0
+
+
+def test_format_slice_rois_text_includes_index_and_order() -> None:
+    rois = {
+        "ROI 2": [(2.0, 2.0, 5.0)],
+        "ROI 1": [(1.0, 1.0, 5.0), (3.0, 3.0, 5.0)],
+    }
+
+    text = _format_slice_rois_text(rois, precision=2)
+
+    assert "ROI 1: 2 points" in text
+    assert "001: (1.00, 1.00, 5.00)" in text
+    assert "002: (3.00, 3.00, 5.00)" in text
+    assert "ROI 2: 1 points" in text
+
+
+def test_format_slice_rois_text_empty() -> None:
+    assert _format_slice_rois_text({}, precision=4) == "(no contours on this slice)"