Initial standalone RTSS diff viewer scaffold

.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+.DS_Store
+.streamlit/

Makefile

@@ -0,0 +1,47 @@
+PYTHON ?= python3
+VENV ?= .venv
+PIP := $(VENV)/bin/pip
+STREAMLIT := $(VENV)/bin/streamlit
+
+SPACE ?= amithjkamath/rtssdiffviewer
+HF_REMOTE ?= hf
+DEPLOY_BRANCH ?= deploy
+
+.PHONY: install run fmt lint clean deploy-init deploy status
+
+install:
+	$(PYTHON) -m venv $(VENV)
+	$(PIP) install --upgrade pip
+	$(PIP) install -r requirements.txt
+
+run:
+	$(STREAMLIT) run app.py
+
+fmt:
+	@echo "No formatter configured."
+
+lint:
+	$(VENV)/bin/python -m py_compile app.py src/rtssdiffviewer/*.py
+
+clean:
+	rm -rf $(VENV) __pycache__ src/rtssdiffviewer/__pycache__
+
+deploy-init:
+	@if git remote | grep -q '^$(HF_REMOTE)$$'; then \
+		git remote set-url $(HF_REMOTE) https://huggingface.co/spaces/$(SPACE); \
+	else \
+		git remote add $(HF_REMOTE) https://huggingface.co/spaces/$(SPACE); \
+	fi
+	@git fetch $(HF_REMOTE) || true
+	@if git show-ref --verify --quiet refs/heads/$(DEPLOY_BRANCH); then \
+		echo "Deploy branch $(DEPLOY_BRANCH) already exists"; \
+	else \
+		git checkout -b $(DEPLOY_BRANCH); \
+		git checkout -; \
+	fi
+
+deploy:
+	bash deploy.sh $(SPACE)
+
+status:
+	@echo "Space URL: https://huggingface.co/spaces/$(SPACE)"

README.md

@@ -0,0 +1,37 @@
+---
+title: RTSS Diff Viewer
+emoji: CT
+colorFrom: blue
+colorTo: cyan
+sdk: streamlit
+sdk_version: 1.55.0
+app_file: app.py
+pinned: false
+---
+
+# RTSS Diff Viewer
+
+A standalone Streamlit app for:
+
+- converting RTSS `.dcm` files to JSON
+- downloading normalized JSON outputs
+- visualizing git-like diffs between two RTSS versions
+- batch-uploading multiple variants and switching any two versions for comparison
+
+## Local Setup
+
+```bash
+make install
+make run
+```
+
+## Hugging Face Spaces Deployment
+
+Use the deploy workflow in this repository:
+
+```bash
+make deploy-init SPACE=amithjkamath/rtssdiffviewer
+make deploy
+```
+
+This pushes local `deploy` branch to Space `main`.

app.py

@@ -0,0 +1,221 @@
+#!/usr/bin/env python3
+"""Streamlit RTSS diff viewer app."""
+
+from __future__ import annotations
+
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import streamlit as st
+
+ROOT = Path(__file__).resolve().parent
+SRC_DIR = ROOT / "src"
+if str(SRC_DIR) not in sys.path:
+    sys.path.insert(0, str(SRC_DIR))
+
+from rtssdiffviewer.dcm_to_json import dcm_to_json  # noqa: E402
+from rtssdiffviewer.diff_core import (  # noqa: E402
+    COMPONENT_KEYS,
+    DEFAULT_VOLATILE_TAG_PREFIXES,
+    normalize_value,
+    pretty_json_text,
+    select_component,
+    unified_diff_text,
+)
+
+try:
+    from st_diff_viewer import diff_viewer
+except Exception:
+    diff_viewer = None
+
+
+def dcm_bytes_to_json_dict(payload: bytes) -> dict[str, Any]:
+    with tempfile.NamedTemporaryFile(suffix=".dcm", delete=False) as tmp:
+        tmp.write(payload)
+        tmp_path = Path(tmp.name)
+    try:
+        return dcm_to_json(tmp_path)
+    finally:
+        tmp_path.unlink(missing_ok=True)
+
+
+def ensure_state() -> None:
+    st.session_state.setdefault("left_name", None)
+    st.session_state.setdefault("right_name", None)
+    st.session_state.setdefault("left_json_raw", None)
+    st.session_state.setdefault("right_json_raw", None)
+    st.session_state.setdefault("batch_variants", {})
+
+
+def render_diff_panel(
+    *,
+    left_name: str,
+    right_name: str,
+    left_raw: dict[str, Any],
+    right_raw: dict[str, Any],
+    component: str,
+    precision: int,
+    keep_volatile: bool,
+    key_prefix: str,
+) -> None:
+    ignore_prefixes: set[str] = set()
+    if not keep_volatile:
+        ignore_prefixes.update(DEFAULT_VOLATILE_TAG_PREFIXES)
+
+    left_selected = select_component(left_raw, component)
+    right_selected = select_component(right_raw, component)
+
+    left_norm = normalize_value(left_selected, precision, ignore_prefixes)
+    right_norm = normalize_value(right_selected, precision, ignore_prefixes)
+
+    left_text = pretty_json_text(left_norm)
+    right_text = pretty_json_text(right_norm)
+
+    col1, col2, col3 = st.columns(3)
+    with col1:
+        st.download_button(
+            "Download left JSON",
+            data=left_text,
+            file_name=f"{Path(left_name).stem}.{component}.json",
+            mime="application/json",
+            key=f"{key_prefix}_dl_left",
+        )
+    with col2:
+        st.download_button(
+            "Download right JSON",
+            data=right_text,
+            file_name=f"{Path(right_name).stem}.{component}.json",
+            mime="application/json",
+            key=f"{key_prefix}_dl_right",
+        )
+
+    diff_text = unified_diff_text(left_text, right_text, left_name, right_name)
+    with col3:
+        st.download_button(
+            "Download unified 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("### Diff View")
+    if diff_viewer is not None:
+        diff_viewer(left_text, right_text, split_view=True)
+    else:
+        if diff_text.strip():
+            st.code(diff_text, language="diff")
+        else:
+            st.success("No differences after normalization and filtering.")
+
+
+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)
+
+    tab_upload, tab_diff, tab_batch = st.tabs(
+        ["1) Upload Pair", "2) Pair Diff", "3) Batch Compare"]
+    )
+
+    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 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.")
+
+    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",
+            )
+
+    with tab_batch:
+        files = st.file_uploader(
+            "Upload RTSS variant set (.dcm)",
+            type=["dcm"],
+            accept_multiple_files=True,
+            key="batch_upload",
+        )
+
+        if st.button("Convert uploaded set", type="primary", key="batch_convert"):
+            if not files:
+                st.warning("Upload at least two RTSS files.")
+            else:
+                converted: dict[str, dict[str, Any]] = {}
+                with st.spinner("Converting variant set..."):
+                    for idx, file in enumerate(files, start=1):
+                        name = file.name
+                        if name in converted:
+                            name = f"{idx:02d}_{name}"
+                        converted[name] = dcm_bytes_to_json_dict(file.getvalue())
+                st.session_state.batch_variants = converted
+                st.success(f"Converted {len(converted)} file(s).")
+
+        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",
+            )
+
+
+if __name__ == "__main__":
+    main()

deploy.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SPACE_NAME="${1:-}"
+if [[ -z "$SPACE_NAME" ]]; then
+  echo "Usage: bash deploy.sh <username/space-name>"
+  exit 1
+fi
+
+if [[ ! -d .git ]]; then
+  echo "Error: run from a git repository"
+  exit 1
+fi
+
+HF_REMOTE="hf"
+DEPLOY_BRANCH="deploy"
+SPACE_URL="https://huggingface.co/spaces/${SPACE_NAME}"
+
+if git remote | grep -q "^${HF_REMOTE}$"; then
+  git remote set-url "${HF_REMOTE}" "${SPACE_URL}"
+else
+  git remote add "${HF_REMOTE}" "${SPACE_URL}"
+fi
+
+if ! git show-ref --verify --quiet "refs/heads/${DEPLOY_BRANCH}"; then
+  git checkout -b "${DEPLOY_BRANCH}"
+fi
+
+CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+if [[ "$CURRENT_BRANCH" != "$DEPLOY_BRANCH" ]]; then
+  git checkout "$DEPLOY_BRANCH"
+fi
+
+git add .
+if ! git diff --staged --quiet; then
+  git commit -m "Deploy RTSS diff viewer"
+fi
+
+git push "${HF_REMOTE}" "${DEPLOY_BRANCH}:main"
+
+echo "Deployment complete: ${SPACE_URL}"

pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "rtssdiffviewer"
+version = "0.1.0"
+description = "Streamlit app for RTSS DICOM to JSON conversion and git-like diffing"
+requires-python = ">=3.10"
+dependencies = [
+  "streamlit>=1.43",
+  "st-diff-viewer>=1.0.7",
+  "pydicom>=3.0.1",
+]
+
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

requirements.txt

@@ -0,0 +1,3 @@
+streamlit>=1.43
+st-diff-viewer>=1.0.7
+pydicom>=3.0.1

src/rtssdiffviewer/__init__.py

@@ -0,0 +1,5 @@
+"""rtssdiffviewer package."""
+
+from .dcm_to_json import dcm_to_json
+
+__all__ = ["dcm_to_json"]

src/rtssdiffviewer/dcm_to_json.py

@@ -0,0 +1,117 @@
+"""DICOM RTSS to JSON conversion helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+import pydicom
+from pydicom.dataelem import DataElement
+from pydicom.dataset import Dataset
+from pydicom.uid import UID
+
+
+def _tag_key(elem: DataElement) -> str:
+    tag_str = f"({elem.tag.group:04X},{elem.tag.element:04X})"
+    keyword = elem.keyword or ""
+    return f"{tag_str} {keyword}".strip()
+
+
+def _bytes_summary(data: bytes) -> dict[str, Any]:
+    return {
+        "_type": "bytes",
+        "length": len(data),
+        "sha256": hashlib.sha256(data).hexdigest(),
+    }
+
+
+def _scalar(value: Any) -> Any:
+    if value is None:
+        return None
+    if isinstance(value, (int, float, bool)):
+        return value
+    if isinstance(value, bytes):
+        return _bytes_summary(value)
+    return str(value)
+
+
+def _convert_value(elem: DataElement) -> Any:
+    vr = elem.VR
+    if vr == "SQ":
+        return [_dataset_to_dict(item) for item in (elem.value or [])]
+
+    if vr in ("OB", "OW", "OD", "OF", "OL", "OV", "UN"):
+        raw = elem.value
+        if isinstance(raw, bytes):
+            return _bytes_summary(raw)
+        return {"_type": "bytes", "length": 0, "sha256": ""}
+
+    if vr == "DS":
+        raw = elem.value
+        if raw is None:
+            return None
+        if hasattr(raw, "__iter__") and not isinstance(raw, str):
+            try:
+                return [float(v) for v in raw]
+            except (TypeError, ValueError):
+                return [str(v) for v in raw]
+        try:
+            return float(raw)
+        except (TypeError, ValueError):
+            return str(raw)
+
+    if vr == "IS":
+        raw = elem.value
+        if raw is None:
+            return None
+        if hasattr(raw, "__iter__") and not isinstance(raw, str):
+            try:
+                return [int(v) for v in raw]
+            except (TypeError, ValueError):
+                return [str(v) for v in raw]
+        try:
+            return int(raw)
+        except (TypeError, ValueError):
+            return str(raw)
+
+    raw = elem.value
+    if hasattr(raw, "__iter__") and not isinstance(raw, (str, bytes, UID)):
+        items = list(raw)
+        if len(items) == 1:
+            return _scalar(items[0])
+        return [_scalar(v) for v in items]
+
+    return _scalar(raw)
+
+
+def _dataset_to_dict(ds: Dataset) -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for elem in ds:
+        key = _tag_key(elem)
+        if elem.keyword == "ContourData" and elem.value:
+            flat = [float(v) for v in elem.value]
+            out[key] = [flat[i : i + 3] for i in range(0, len(flat), 3)]
+        else:
+            out[key] = _convert_value(elem)
+    return out
+
+
+def dcm_to_json(dcm_path: str | Path, output_path: str | Path | None = None) -> dict[str, Any]:
+    """Convert DICOM file to a deterministic JSON dict and optionally write it."""
+    dcm_path = Path(dcm_path)
+    ds = pydicom.dcmread(str(dcm_path), force=True)
+
+    result: dict[str, Any] = {}
+    if hasattr(ds, "file_meta") and ds.file_meta:
+        result["_file_meta"] = _dataset_to_dict(ds.file_meta)
+    result.update(_dataset_to_dict(ds))
+
+    if output_path is not None:
+        output_path = Path(output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        with output_path.open("w", encoding="utf-8") as fh:
+            json.dump(result, fh, indent=2, ensure_ascii=False, sort_keys=False)
+
+    return result

src/rtssdiffviewer/diff_core.py

@@ -0,0 +1,83 @@
+"""Core RTSS JSON normalization and diff helpers."""
+
+from __future__ import annotations
+
+import difflib
+import json
+from typing import Any
+
+DEFAULT_VOLATILE_TAG_PREFIXES = {
+    "(0008,0012)",
+    "(0008,0013)",
+    "(0008,0018)",
+    "(0020,000D)",
+    "(0020,000E)",
+    "(0020,0052)",
+    "(3006,0008)",
+    "(3006,0009)",
+}
+
+COMPONENT_KEYS = {
+    "references": ["(3006,0010) ReferencedFrameOfReferenceSequence"],
+    "structures": [
+        "(3006,0020) StructureSetROISequence",
+        "(3006,0080) RTROIObservationsSequence",
+    ],
+    "contours": ["(3006,0039) ROIContourSequence"],
+}
+
+
+def is_volatile_tag(key: str, ignore_prefixes: set[str]) -> bool:
+    if not key.startswith("("):
+        return False
+    tag_prefix = key.split(" ", 1)[0]
+    return tag_prefix in ignore_prefixes
+
+
+def normalize_value(value: Any, precision: int, ignore_prefixes: set[str]) -> Any:
+    if isinstance(value, dict):
+        out: dict[str, Any] = {}
+        for key in sorted(value.keys()):
+            if is_volatile_tag(key, ignore_prefixes):
+                continue
+            out[key] = normalize_value(value[key], precision, ignore_prefixes)
+        return out
+
+    if isinstance(value, list):
+        return [normalize_value(v, precision, ignore_prefixes) for v in value]
+
+    if isinstance(value, float):
+        return round(value, precision)
+
+    return value
+
+
+def select_component(data: dict[str, Any], component: str) -> dict[str, Any]:
+    if component == "all":
+        return data
+
+    if component == "metadata":
+        excluded: set[str] = set()
+        for keys in COMPONENT_KEYS.values():
+            excluded.update(keys)
+        return {k: v for k, v in data.items() if k not in excluded}
+
+    keys = COMPONENT_KEYS[component]
+    return {k: data[k] for k in keys if k in data}
+
+
+def pretty_json_text(data: dict[str, Any]) -> str:
+    return json.dumps(data, indent=2, ensure_ascii=False, sort_keys=True)
+
+
+def unified_diff_text(left_text: str, right_text: str, left_name: str, right_name: str) -> str:
+    left_lines = [line + "\n" for line in left_text.splitlines()]
+    right_lines = [line + "\n" for line in right_text.splitlines()]
+    diff = difflib.unified_diff(
+        left_lines,
+        right_lines,
+        fromfile=left_name,
+        tofile=right_name,
+        lineterm="",
+    )
+    return "\n".join(diff)