updated interface for app

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 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 \

README.md

@@ -18,13 +18,31 @@ A standalone Streamlit app for:
 - visualizing git-like diffs between two RTSS versions
 - batch-uploading multiple variants and switching any two versions for comparison
 
-## Local Setup
+## User Workflows
+
+- `Instructions` mode: in-app overview of Pair Mode and Batch Compare usage.
+- `Pair Mode`: upload two RTSS files, inspect structured diff, and view contour points in 3D.
+- `Batch Compare`: upload multiple RTSS files and compare any two using unified text diff.
+
+## 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
@@ -58,6 +60,9 @@ 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()
@@ -101,8 +106,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 +131,568 @@ 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 3D 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 text-based and visual workflows.")
+
+        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("5. Open 3D Contour View to compare contour points visually.")
+        st.write("6. In 3D view, red points are from the first RTSS and green points are from the second RTSS.")
+
+        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. Review the unified text diff and download outputs if needed.")
+
+        st.markdown("### Tips")
+        st.write("- Large comparisons automatically switch to unified text diff for faster loading.")
+        st.write("- In 3D view, drag to rotate and scroll to zoom.")
+
+    elif app_mode == "Pair Mode":
+        tab_upload, tab_diff, tab_points_3d = st.tabs(
+            ["1) Upload Pair", "2) Pair Diff", "3) 3D Contour View"]
+        )
 
-        if st.button("Convert pair", type="primary"):
-            if left_file is None or right_file is None:
-                st.warning("Upload both files first.")
+        with tab_upload:
+            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.success("Pair conversion complete.")
+                    st.info("Next step: open tab 2) Pair Diff to review differences.")
+
+        with tab_diff:
+            st.info("Step 2 of 3: Review Pair Diff, then move to tab 3) 3D Contour View.")
+            component_options = ["all", "metadata", *COMPONENT_KEYS.keys()]
+            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 tab 1 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.")
-        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",
-            )
+                st.caption("If files are large, diff generation may take some time while JSON is normalized and compared.")
+                with st.spinner("Preparing normalized JSON and building diff view. This may take time for large files..."):
+                    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.info("Next step: open tab 3) 3D Contour View for point cloud comparison.")
+
+        with tab_points_3d:
+            st.markdown("### 3D Contour Point Cloud")
+            st.info("Step 3 of 3: Inspect contour points in 3D. Red is first RTSS, green is second RTSS.")
+            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.")
+            else:
+                st.caption("Contour extraction and 3D plot generation can take time for large RTSS files.")
+                with st.spinner("Extracting contour points and rendering interactive 3D view. Please wait..."):
+                    render_contour_point_cloud(
+                        left_name=st.session_state.left_name,
+                        right_name=st.session_state.right_name,
+                        left_raw=left_raw,
+                        right_raw=right_raw,
+                    )
 
-    with tab_batch:
+    else:
+        st.markdown("### Batch Compare")
         files = st.file_uploader(
             "Upload RTSS variant set (.dcm)",
             type=["dcm"],
@@ -189,32 +717,42 @@ def main() -> None:
         variants = st.session_state.batch_variants
         if not variants:
             st.info("No batch set loaded yet.")
-            return
-
-        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")
-
-        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",
-            )
+            names = sorted(variants.keys())
+            if len(names) < 2:
+                st.warning("Need at least two variants.")
+            else:
+                component_options = ["all", "metadata", *COMPONENT_KEYS.keys()]
+                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")
+
+                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,
+                        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

tests/test_app_features.py

@@ -0,0 +1,162 @@
+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 (
+    _extract_volume_bounds_from_rtss,
+    _merge_bounds,
+    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,
+    }