Add D3 comparison scaffold

.gitignore

@@ -2,5 +2,13 @@ cpp/build/
 .vscode/
 *.ipynb
 
+# Local dev-container data landing zone (e.g. azcopy pulls of large .mrd files)
+mrd-viz/data/
+
 *.bin
 *.png
+*.vsix
+
+mrd-viz/extension/mrd-viz/media/backend/
+
+*.pyc

mrd-viz/backend/packaging/testfile.txt

@@ -0,0 +1 @@
+test

mrd-viz/docs/RESEARCHER_ONBOARDING_AND_ROADMAP.md

@@ -0,0 +1,25 @@
+# MRD Viz researcher onboarding and roadmap
+
+This plan keeps the first delivery focused on the smallest experience that already feels useful to researchers:
+
+- D1 delivers a file-first viewer that opens `.mrd` files directly in VS Code.
+- Release packages that experience into a `.vsix` that can be installed from GitHub Releases.
+- The later milestones can continue in parallel, but they do not block the first researcher-facing release.
+
+## Functionality table
+
+| Milestone | Before UX | After UX | Functions created | Why it matters |
+| --- | --- | --- | --- | --- |
+| D1 | Researchers need a source checkout, manual backend setup, and a dev-host workflow to inspect `.mrd` files. | Researchers can install the extension, point it at a Python backend, and open a local `.mrd` file in a normal VS Code window. | Custom editor for `.mrd`, open-file command, backend interpreter selection, thumbnail mosaic preview, on-demand full-resolution image loading, metadata panels. | This is the first “real” researcher UX: inspect MRD data without a custom dev environment. |
+| Release | There is no simple installable artifact for non-developers. | Researchers can install a packaged `.vsix` from a GitHub Release with a single command such as `code --install-extension mrd-viz-*.vsix`. | VSIX packaging workflow, release automation, packaging runbook, installation guidance. | This removes the biggest onboarding friction for early adopters. |
+| D2 | A single file is viewable, but metadata navigation is still coarse. | Researchers can inspect acquisition, waveform, and raw metadata with clearer grouping and search. | Structured metadata summaries, improved panels, richer navigation between preview and metadata. | Makes it easier to understand what a file contains before deeper analysis. |
+| D3 | Users can inspect one file at a time, which makes comparison work awkward. | Researchers can compare multiple MRD files side by side or in a multi-file review flow. | Multi-file selection, comparison view, synchronized thumbnail and metadata inspection. | Reduces manual effort when comparing reconstructions or runs. |
+| Marketplace | Distribution is limited to local installs and GitHub Releases. | Researchers can discover and install the extension from the VS Code Marketplace. | Publisher setup, Marketplace publishing flow, marketplace metadata and branding. | This broadens reach once the core experience is stable. |
+| F10 | Backend setup is still a manual step and the first-run experience is uneven. | Researchers get guided backend bootstrap, clearer first-run messages, and fewer setup failures. | Backend auto-detection, setup wizard, robust setup diagnostics, clearer error pages. | This closes the remaining onboarding gap for less technical users. |
+| Future ops / support | Researchers can open files, but support and diagnostics are ad hoc. | Teams can collect clear logs, report failures, and troubleshoot the backend more easily. | Better diagnostics, telemetry-safe logging, support docs, known-issue guidance. | Keeps the workflow sustainable as adoption grows. |
+
+## Recommended shipping order
+
+1. Ship D1 + Release together as the first researcher-facing milestone.
+2. Keep D2 and D3 moving in parallel behind that milestone so feedback can guide the next iteration.
+3. Treat Marketplace and F10 as follow-on work that improves discoverability and onboarding after the core flow is proven.

mrd-viz/extension/mrd-viz/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Change Log
+
+All notable changes to the "mrd-viz" extension will be documented in this file.
+
+Check [Keep a Changelog](http://keepachangelog.com/) for recommendations on how to structure this file.
+
+## [Unreleased]
+
+- Added researcher-facing quick-start guidance for VSIX installation and backend setup.
+- Documented the D1 + release roadmap and the broader functionality sequence for future milestones.
+- Added an initial D3 comparison scaffold command that lets users select multiple `.mrd` files and open a placeholder compare view.

mrd-viz/extension/mrd-viz/README.md

@@ -0,0 +1,54 @@
+# MRD Viz
+
+A Visual Studio Code extension for inspecting [MRD](https://github.com/ismrmrd/mrd) (Magnetic Resonance Data) files directly in the editor. Open a `.mrd` file to view a thumbnail mosaic of its images alongside acquisition, waveform, and header metadata.
+
+## Features
+
+- Opens `.mrd` files in a custom editor (thumbnail mosaic + metadata panels).
+- Select a tile to load its full-resolution image on demand.
+- Browse image, acquisition, waveform, and raw-stream metadata, including a raw JSON view.
+- Start the D3 comparison scaffold by selecting multiple `.mrd` files and opening the new compare view.
+
+## Quick start for researchers
+
+The first researcher-friendly path is a packaged VSIX from a GitHub Release:
+
+1. Download the latest `mrd-viz-*.vsix` from the MRD Viz GitHub Release assets.
+2. Install it with `code --install-extension mrd-viz-*.vsix`.
+3. Create or point MRD Viz at a Python 3.12 environment that has the `mrd_viz` backend installed.
+4. Open a local `.mrd` file (or run `MRD Viz: Open File`) to view it in a regular VS Code window.
+
+For the backend setup, the extension looks for the interpreter configured in `mrdViz.pythonPath`; a local development checkout can also auto-detect `mrd-viz/backend/.venv`.
+
+See [mrd-viz/docs/RESEARCHER_ONBOARDING_AND_ROADMAP.md](../../docs/RESEARCHER_ONBOARDING_AND_ROADMAP.md) for the phased D1/release roadmap and the broader functionality plan.
+
+## Requirements
+
+MRD Viz relies on a Python backend (the `mrd_viz` package) to read `.mrd` files. You need:
+
+- Python 3.12
+- The `mrd_viz` backend installed into an environment the extension can find.
+
+Point the extension at the interpreter with the `mrdViz.pythonPath` setting (see below). During local development the extension also auto-detects a virtual environment at `mrd-viz/backend/.venv`.
+
+## Extension Settings
+
+This extension contributes the following settings:
+
+- `mrdViz.pythonPath`: Python executable used to run `python -m mrd_viz.cli`. Set this to the backend environment's interpreter.
+- `mrdViz.maxThumbnails`: Maximum number of image thumbnails requested for the initial view (default `128`).
+- `mrdViz.backendTimeoutMs`: Timeout in milliseconds for a single backend process (default `30000`).
+
+## Commands
+
+- `MRD Viz: Open File` — open the selected or picked `.mrd` file in MRD Viz.
+
+## Known Issues
+
+- Non-`.mrd` files and non-`file://` resources are rejected with a warning; only local `.mrd` files are supported.
+
+## Release Notes
+
+### 0.0.1
+
+Initial preview: custom editor, thumbnail mosaic, on-demand full-resolution images, and metadata panels.

mrd-viz/extension/mrd-viz/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "mrd-viz",
+  "displayName": "MRD Viz",
+  "description": "MRD file viewer for VS Code",
+  "version": "0.0.1",
+  "publisher": "ismrmrd",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ismrmrd/mrd.git"
+  },
+  "engines": {
+    "vscode": "^1.120.0"
+  },
+  "categories": [
+    "Other"
+  ],
+  "main": "./out/extension.js",
+  "activationEvents": [],
+  "contributes": {
+    "commands": [
+      {
+        "command": "mrd-viz.openFile",
+        "title": "Open File",
+        "category": "MRD Viz"
+      },
+      {
+        "command": "mrd-viz.setUpBackend",
+        "title": "Set Up Backend",
+        "category": "MRD Viz"
+      },
+      {
+        "command": "mrd-viz.selectInterpreter",
+        "title": "Select Python Interpreter",
+        "category": "MRD Viz"
+      },
+      {
+        "command": "mrd-viz.compareFiles",
+        "title": "Compare Files (D3 scaffolding)",
+        "category": "MRD Viz"
+      }
+    ],
+    "customEditors": [
+      {
+        "viewType": "mrd-viz.mrdFile",
+        "displayName": "MRD Viz",
+        "selector": [
+          {
+            "filenamePattern": "*.mrd"
+          }
+        ],
+        "priority": "default"
+      }
+    ],
+    "configuration": {
+      "title": "MRD Viz",
+      "properties": {
+        "mrdViz.pythonPath": {
+          "type": "string",
+          "default": "python",
+          "markdownDescription": "Python executable used to run `python -m mrd_viz.cli`. Set this to the backend virtual environment interpreter when needed."
+        },
+        "mrdViz.maxThumbnails": {
+          "type": "number",
+          "default": 128,
+          "minimum": 0,
+          "markdownDescription": "Maximum number of MRD image thumbnails requested from the backend for the initial open-file payload."
+        },
+        "mrdViz.backendTimeoutMs": {
+          "type": "number",
+          "default": 30000,
+          "minimum": 1000,
+          "markdownDescription": "Timeout in milliseconds for one short-lived MRD Viz backend process."
+        }
+      }
+    },
+    "menus": {
+      "explorer/context": [
+        {
+          "command": "mrd-viz.openFile",
+          "when": "resourceExtname == .mrd",
+          "group": "navigation"
+        },
+        {
+          "command": "mrd-viz.compareFiles",
+          "when": "resourceExtname == .mrd",
+          "group": "navigation"
+        }
+      ]
+    }
+  },
+  "scripts": {
+    "vscode:prepublish": "npm run compile",
+    "compile": "tsc -p ./",
+    "watch": "tsc -watch -p ./",
+    "pretest": "npm run compile && npm run lint",
+    "lint": "eslint src",
+    "test": "vscode-test"
+  },
+  "devDependencies": {
+    "@types/vscode": "^1.120.0",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "22.x",
+    "typescript-eslint": "^8.56.1",
+    "eslint": "^9.39.3",
+    "typescript": "^5.9.3",
+    "@vscode/test-cli": "^0.0.12",
+    "@vscode/test-electron": "^2.5.2"
+  },
+  "overrides": {
+    "diff": "^8.0.3",
+    "serialize-javascript": "^7.0.5"
+  }
+}

mrd-viz/extension/mrd-viz/src/d3Scaffold.ts

@@ -0,0 +1,44 @@
+import * as path from 'node:path';
+import * as vscode from 'vscode';
+
+export function getD3ScaffoldHtml(webview: vscode.Webview, files: readonly vscode.Uri[]): string {
+	const cspSource = webview.cspSource;
+	const fileItems = files.map(file => {
+		const label = path.basename(file.fsPath);
+		return `<li><code>${escapeHtml(label)}</code></li>`;
+	}).join('');
+
+	return `<!DOCTYPE html>
+	<html lang="en">
+	<head>
+		<meta charset="UTF-8">
+		<meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src ${cspSource} 'unsafe-inline'; img-src ${cspSource};">
+		<meta name="viewport" content="width=device-width, initial-scale=1.0">
+		<title>MRD Viz Comparison Scaffold</title>
+		<style>
+			body { font-family: var(--vscode-font-family); color: var(--vscode-foreground); background: var(--vscode-editor-background); padding: 24px; }
+			.card { border: 1px solid var(--vscode-panel-border); border-radius: 8px; padding: 16px; max-width: 720px; }
+			code { font-family: var(--vscode-editor-font-family); background: var(--vscode-textCodeBlock-background); padding: 2px 4px; border-radius: 4px; }
+			ul { padding-left: 20px; }
+		</style>
+	</head>
+	<body>
+		<div class="card">
+			<h1>MRD Viz D3 scaffolding</h1>
+			<p>This placeholder view is the first step for the upcoming multi-file comparison experience.</p>
+			<p>Selected files:</p>
+			<ul>${fileItems}</ul>
+			<p>Next steps for D3: add synchronized thumbnails, side-by-side metadata, and a shared selection model.</p>
+		</div>
+	</body>
+	</html>`;
+}
+
+function escapeHtml(value: string): string {
+	return value
+		.replace(/&/g, '&amp;')
+		.replace(/</g, '&lt;')
+		.replace(/>/g, '&gt;')
+		.replace(/"/g, '&quot;')
+		.replace(/'/g, '&#39;');
+}