dcmview-py 0.2.2__py3-none-win_amd64.whl

dcmview_py/__init__.py

@@ -0,0 +1,5 @@
+"""Python wrapper package for launching dcmview."""
+
+from .wrapper import ShutdownHandle, view
+
+__all__ = ["ShutdownHandle", "view"]

dcmview_py/__main__.py

@@ -0,0 +1,76 @@
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess
+import sys
+from importlib import metadata
+from pathlib import Path
+from typing import Optional, Sequence
+
+from .wrapper import view
+
+
+def _package_version() -> str:
+	try:
+		return metadata.version("dcmview-py")
+	except metadata.PackageNotFoundError:
+		pyproject = Path(__file__).resolve().parents[2] / "pyproject.toml"
+		if not pyproject.is_file():
+			return "unknown"
+		match = re.search(
+			r'(?m)^\[project\]\s*(?:\n(?!\[).*)*?\nversion\s*=\s*"([^"]+)"',
+			pyproject.read_text(encoding="utf-8"),
+		)
+		return match.group(1) if match else "unknown"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+	parser = argparse.ArgumentParser(prog="python -m dcmview_py")
+	parser.add_argument("--version", action="version", version=f"dcmview {_package_version()}")
+	parser.add_argument("paths", nargs="+", help="One or more DICOM file or directory paths")
+	parser.add_argument("-p", "--port", type=int, default=0)
+	parser.add_argument("--host", default="127.0.0.1")
+	parser.add_argument("--no-browser", action="store_true")
+	parser.add_argument("--tunnel", action="store_true")
+	parser.add_argument("--tunnel-host")
+	parser.add_argument("--tunnel-port", type=int, default=0)
+	parser.add_argument("--timeout", type=int)
+	parser.add_argument("--no-recursive", action="store_true")
+	parser.add_argument("--annotations")
+	return parser
+
+
+def run_cli(argv: Optional[Sequence[str]] = None) -> int:
+	parser = _build_parser()
+	args = parser.parse_args(argv)
+
+	try:
+		view(
+			args.paths,
+			port=args.port,
+			host=args.host,
+			browser=not args.no_browser,
+			tunnel=args.tunnel,
+			tunnel_host=args.tunnel_host,
+			tunnel_port=args.tunnel_port,
+			recursive=not args.no_recursive,
+			timeout=args.timeout,
+			annotations=args.annotations,
+			block=True,
+		)
+	except subprocess.CalledProcessError as error:
+		return int(error.returncode)
+	except (RuntimeError, ValueError, TypeError) as error:
+		print(str(error), file=sys.stderr)
+		return 1
+
+	return 0
+
+
+def main() -> None:
+	raise SystemExit(run_cli())
+
+
+if __name__ == "__main__":
+	main()

dcmview_py/wrapper.py

@@ -0,0 +1,474 @@
+from __future__ import annotations
+
+import os
+import json
+import shutil
+import signal
+import subprocess
+import sys
+import threading
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Iterable, Optional, Union
+
+_STARTUP_PREFIX = "dcmview: server running at "
+_STARTUP_EVENT_TYPE = "server_started"
+_URL_WAIT_SECONDS = 5.0
+_STOP_TIMEOUT_SECONDS = 5.0
+_BINARY_ENV = "DCMVIEW_BINARY"
+_VSCODE_BRIDGE_URL_ENV = "DCMVIEW_VSCODE_BRIDGE_URL"
+_VSCODE_BRIDGE_TOKEN_ENV = "DCMVIEW_VSCODE_BRIDGE_TOKEN"
+_VSCODE_BRIDGE_BYPASS_ENV = "DCMVIEW_VSCODE_BYPASS"
+
+PathInput = Union[str, os.PathLike[str]]
+
+
+class _OutputMonitor:
+	def __init__(self, process: subprocess.Popen[str]) -> None:
+		self._process = process
+		self._url: Optional[str] = None
+		self._url_lock = threading.Lock()
+		self._startup_json_unsupported = False
+		self._startup_json_unsupported_lock = threading.Lock()
+		self._url_ready = threading.Event()
+		self._thread = threading.Thread(target=self._run, name="dcmview-py-output", daemon=True)
+
+	def start(self) -> None:
+		self._thread.start()
+
+	def join(self) -> None:
+		self._thread.join()
+
+	def wait_for_url(self, timeout: float) -> Optional[str]:
+		self._url_ready.wait(timeout)
+		return self.url
+
+	@property
+	def url(self) -> Optional[str]:
+		with self._url_lock:
+			return self._url
+
+	@property
+	def startup_json_unsupported(self) -> bool:
+		with self._startup_json_unsupported_lock:
+			return self._startup_json_unsupported
+
+	def _set_url(self, url: str) -> None:
+		with self._url_lock:
+			if self._url is None:
+				self._url = url
+				self._url_ready.set()
+
+	def _set_startup_json_unsupported(self) -> None:
+		with self._startup_json_unsupported_lock:
+			self._startup_json_unsupported = True
+
+	def _run(self) -> None:
+		stdout = self._process.stdout
+		if stdout is None:
+			self._url_ready.set()
+			return
+
+		try:
+			for line in stdout:
+				sys.stdout.write(line)
+				sys.stdout.flush()
+				url = _parse_startup_url(line)
+				if url is not None:
+					self._set_url(url)
+				if _is_startup_json_unsupported_line(line):
+					self._set_startup_json_unsupported()
+		finally:
+			stdout.close()
+			self._url_ready.set()
+
+
+class ShutdownHandle:
+	"""Handle for controlling a non-blocking dcmview subprocess."""
+
+	def __init__(self, process: subprocess.Popen[str], monitor: _OutputMonitor) -> None:
+		self._process = process
+		self._monitor = monitor
+
+	@property
+	def url(self) -> Optional[str]:
+		return self._monitor.url
+
+	def stop(self, timeout: float = _STOP_TIMEOUT_SECONDS) -> int:
+		if self._process.poll() is not None:
+			self._monitor.join()
+			return int(self._process.returncode or 0)
+
+		try:
+			self._process.send_signal(_graceful_stop_signal())
+		except (ProcessLookupError, ValueError):
+			self._monitor.join()
+			return int(self._process.returncode or 0)
+		try:
+			return_code = self._process.wait(timeout=timeout)
+		except subprocess.TimeoutExpired:
+			self._process.terminate()
+			try:
+				return_code = self._process.wait(timeout=timeout)
+			except subprocess.TimeoutExpired:
+				self._process.kill()
+				return_code = self._process.wait(timeout=timeout)
+
+		self._monitor.join()
+		return int(return_code)
+
+	def __enter__(self) -> ShutdownHandle:
+		return self
+
+	def __exit__(self, _exc_type, _exc, _tb) -> None:
+		self.stop()
+
+
+class BridgeShutdownHandle:
+	"""Handle for controlling a VS Code-managed dcmview session."""
+
+	def __init__(self, session_id: str, url: str) -> None:
+		self._session_id = session_id
+		self._url = url
+
+	@property
+	def url(self) -> Optional[str]:
+		return self._url
+
+	def stop(self, timeout: float = _STOP_TIMEOUT_SECONDS) -> int:
+		_bridge_json_request("POST", f"/sessions/{self._session_id}/stop", timeout=timeout)
+		response = _bridge_json_request("GET", f"/sessions/{self._session_id}/wait", timeout=timeout)
+		return int(response.get("exitCode") or 0)
+
+	def __enter__(self) -> BridgeShutdownHandle:
+		return self
+
+	def __exit__(self, _exc_type, _exc, _tb) -> None:
+		self.stop()
+
+
+def view(
+	files: PathInput | Iterable[PathInput],
+	*,
+	port: int = 0,
+	host: str = "127.0.0.1",
+	browser: bool = True,
+	tunnel: bool = False,
+	tunnel_host: Optional[str] = None,
+	tunnel_port: int = 0,
+	block: bool = True,
+	recursive: bool = True,
+	timeout: Optional[int] = None,
+	annotations: Optional[PathInput] = None,
+) -> Optional[ShutdownHandle | BridgeShutdownHandle]:
+	"""Launch dcmview for one or more filesystem paths."""
+
+	paths = _normalize_files(files)
+	annotation_path = _normalize_optional_path(annotations, field_name="annotations")
+	args = _build_args(
+		paths,
+		port=port,
+		host=host,
+		browser=browser,
+		tunnel=tunnel,
+		tunnel_host=tunnel_host,
+		tunnel_port=tunnel_port,
+		recursive=recursive,
+		timeout=timeout,
+		annotations=annotation_path,
+	)
+	if _bridge_available():
+		try:
+			return _view_via_vscode_bridge(args, block=block)
+		except (RuntimeError, OSError, urllib.error.URLError) as error:
+			print(
+				f"dcmview: VS Code bridge unavailable ({error}); falling back to local viewer",
+				file=sys.stderr,
+			)
+
+	for include_startup_json in (True, False):
+		command = _build_command(
+			paths,
+			port=port,
+			host=host,
+			browser=browser,
+			tunnel=tunnel,
+			tunnel_host=tunnel_host,
+			tunnel_port=tunnel_port,
+			recursive=recursive,
+			timeout=timeout,
+			annotations=annotation_path,
+			include_startup_json=include_startup_json,
+		)
+
+		process = subprocess.Popen(command, **_popen_options())
+		monitor = _OutputMonitor(process)
+		monitor.start()
+
+		if block:
+			return_code = process.wait()
+			monitor.join()
+			if return_code != 0:
+				if include_startup_json and monitor.startup_json_unsupported:
+					continue
+				raise subprocess.CalledProcessError(return_code, command)
+			return None
+
+		monitor.wait_for_url(_URL_WAIT_SECONDS)
+		if process.poll() is not None and process.returncode not in (0, None):
+			monitor.join()
+			if include_startup_json and monitor.startup_json_unsupported:
+				continue
+			raise subprocess.CalledProcessError(int(process.returncode), command)
+
+		return ShutdownHandle(process, monitor)
+
+	raise RuntimeError("dcmview failed to start")
+
+
+def _view_via_vscode_bridge(
+	args: list[str],
+	*,
+	block: bool,
+) -> Optional[BridgeShutdownHandle]:
+	response = _bridge_json_request(
+		"POST",
+		"/launch",
+		{
+			"program": "dcmview_py",
+			"args": args,
+			"cwd": os.getcwd(),
+			"wait": False,
+		},
+	)
+	session_id = str(response["sessionId"])
+	url = str(response["url"])
+	print(f"dcmview: opened in VS Code at {url}")
+
+	if not block:
+		return BridgeShutdownHandle(session_id, url)
+
+	wait_response = _bridge_json_request("GET", f"/sessions/{session_id}/wait")
+	exit_code = int(wait_response.get("exitCode") or 0)
+	if exit_code != 0:
+		raise subprocess.CalledProcessError(exit_code, ["dcmview-vscode-bridge", *args])
+	return None
+
+
+def _normalize_files(files: PathInput | Iterable[PathInput]) -> list[str]:
+	if isinstance(files, (str, os.PathLike)):
+		candidates: list[PathInput] = [files]
+	else:
+		candidates = list(files)
+
+	if not candidates:
+		raise ValueError("at least one file path is required")
+
+	normalized: list[str] = []
+	for candidate in candidates:
+		if not isinstance(candidate, (str, os.PathLike)):
+			raise TypeError("files must be path-like values")
+		normalized.append(str(Path(candidate)))
+	return normalized
+
+
+def _normalize_optional_path(path: Optional[PathInput], *, field_name: str) -> Optional[str]:
+	if path is None:
+		return None
+	if not isinstance(path, (str, os.PathLike)):
+		raise TypeError(f"{field_name} must be a path-like value")
+	return str(Path(path))
+
+
+def _build_command(
+	paths: list[str],
+	*,
+	port: int,
+	host: str,
+	browser: bool,
+	tunnel: bool,
+	tunnel_host: Optional[str],
+	tunnel_port: int,
+	recursive: bool,
+	timeout: Optional[int],
+	annotations: Optional[str],
+	include_startup_json: bool = True,
+) -> list[str]:
+	return [
+		_resolve_binary(),
+		*_build_args(
+			paths,
+			port=port,
+			host=host,
+			browser=browser,
+			tunnel=tunnel,
+			tunnel_host=tunnel_host,
+			tunnel_port=tunnel_port,
+			recursive=recursive,
+			timeout=timeout,
+			annotations=annotations,
+			include_startup_json=include_startup_json,
+		),
+	]
+
+
+def _build_args(
+	paths: list[str],
+	*,
+	port: int,
+	host: str,
+	browser: bool,
+	tunnel: bool,
+	tunnel_host: Optional[str],
+	tunnel_port: int,
+	recursive: bool,
+	timeout: Optional[int],
+	annotations: Optional[str],
+	include_startup_json: bool = True,
+) -> list[str]:
+	if tunnel and not tunnel_host:
+		raise ValueError("tunnel_host is required when tunnel=True")
+
+	command = ["--port", str(port), "--host", host]
+	if include_startup_json:
+		command.append("--startup-json")
+	if not browser:
+		command.append("--no-browser")
+	if tunnel:
+		command.append("--tunnel")
+		command.extend(["--tunnel-host", str(tunnel_host), "--tunnel-port", str(tunnel_port)])
+	if timeout is not None:
+		command.extend(["--timeout", str(timeout)])
+	if not recursive:
+		command.append("--no-recursive")
+	if annotations is not None:
+		command.extend(["--annotations", annotations])
+	command.extend(paths)
+	return command
+
+
+def _parse_startup_url(line: str) -> Optional[str]:
+	trimmed = line.strip()
+	if trimmed.startswith("{"):
+		try:
+			event = json.loads(trimmed)
+		except json.JSONDecodeError:
+			return None
+		if (
+			isinstance(event, dict)
+			and event.get("type") == _STARTUP_EVENT_TYPE
+			and isinstance(event.get("url"), str)
+			and event["url"]
+		):
+			return event["url"]
+		return None
+
+	if trimmed.startswith(_STARTUP_PREFIX):
+		url = trimmed[len(_STARTUP_PREFIX) :].strip()
+		return url or None
+	return None
+
+
+def _is_startup_json_unsupported_line(line: str) -> bool:
+	normalized = line.lower()
+	return "--startup-json" in normalized and any(
+		marker in normalized
+		for marker in [
+			"unexpected",
+			"unrecognized",
+			"unknown",
+			"wasn't expected",
+			"was not expected",
+			"found argument",
+		]
+	)
+
+
+def _bridge_available() -> bool:
+	return (
+		os.environ.get(_VSCODE_BRIDGE_BYPASS_ENV) != "1"
+		and bool(os.environ.get(_VSCODE_BRIDGE_URL_ENV))
+		and bool(os.environ.get(_VSCODE_BRIDGE_TOKEN_ENV))
+	)
+
+
+def _bridge_json_request(
+	method: str,
+	path: str,
+	payload: Optional[dict[str, object]] = None,
+	*,
+	timeout: float = _STOP_TIMEOUT_SECONDS,
+) -> dict[str, object]:
+	base_url = os.environ[_VSCODE_BRIDGE_URL_ENV].rstrip("/")
+	token = os.environ[_VSCODE_BRIDGE_TOKEN_ENV]
+	body = None if payload is None else json.dumps(payload).encode("utf-8")
+	request = urllib.request.Request(
+		f"{base_url}{path}",
+		data=body,
+		method=method,
+		headers={
+			"Authorization": f"Bearer {token}",
+			"Content-Type": "application/json",
+		},
+	)
+	with urllib.request.urlopen(request, timeout=timeout) as response:
+		return json.loads(response.read().decode("utf-8"))
+
+
+def _resolve_binary() -> str:
+	configured = os.environ.get(_BINARY_ENV)
+	if configured:
+		candidate = Path(configured).expanduser()
+		if candidate.is_file():
+			_ensure_executable(candidate)
+			return str(candidate)
+		raise RuntimeError(f"{_BINARY_ENV} points to a missing file: {candidate}")
+
+	bundled = Path(__file__).resolve().parent / "bin" / _binary_name()
+	if bundled.is_file():
+		_ensure_executable(bundled)
+		return str(bundled)
+
+	path_binary = shutil.which(_binary_name())
+	if path_binary is not None:
+		return path_binary
+
+	raise RuntimeError(
+		"dcmview binary not found — install a bundled wheel or install the Rust binary separately"
+	)
+
+
+def _binary_name() -> str:
+	return "dcmview.exe" if _is_windows() else "dcmview"
+
+
+def _is_windows() -> bool:
+	return os.name == "nt"
+
+
+def _popen_options() -> dict[str, object]:
+	options: dict[str, object] = {
+		"stdout": subprocess.PIPE,
+		"stderr": subprocess.STDOUT,
+		"text": True,
+		"bufsize": 1,
+	}
+	if _is_windows():
+		options["creationflags"] = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+	return options
+
+
+def _graceful_stop_signal() -> signal.Signals | int:
+	if _is_windows():
+		return getattr(signal, "CTRL_BREAK_EVENT", signal.SIGTERM)
+	return signal.SIGINT
+
+
+def _ensure_executable(path: Path) -> None:
+	if _is_windows() or os.access(path, os.X_OK):
+		return
+
+	mode = path.stat().st_mode
+	exec_bits = (mode & 0o444) >> 2
+	path.chmod(mode | exec_bits)

dcmview_py-0.2.2.dist-info/METADATA

@@ -0,0 +1,437 @@
+Metadata-Version: 2.4
+Name: dcmview-py
+Version: 0.2.2
+Summary: Fast temporary DICOM viewer for local and remote research workflows
+Author: Beatrice Brown-Mulry
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# dcmview
+
+`dcmview` is a fast, temporary DICOM viewer for research and development work.
+Point it at one or more DICOM files from the command line or Python, and it
+starts a local browser viewer for images, tags, cine playback, and rectangular
+ROI annotations. Stop the process and the server is gone.
+
+The main problem it solves is remote-server inspection. Medical imaging research
+often happens where the data already live: an SSH session, a shared compute
+server, or a locked-down institutional network. Viewing those images usually
+means choosing between slow notebook plots, setting up a web viewer on the
+server, opening firewall ports, or uploading data and annotations into a
+third-party cloud tool. `dcmview` keeps the workflow local to the machine with
+the files: start the viewer, forward the loopback port over SSH when needed, and
+inspect the study in seconds.
+
+`dcmview` is intended for developer and research inspection, not clinical
+diagnosis.
+
+## Why use it?
+
+- Inspect DICOM files where they already are, including remote servers.
+- Avoid notebook-based frame rendering for multi-frame studies.
+- Keep data off third-party viewers when all you need is quick review.
+- Open a browser UI with familiar viewer tools: pan, zoom, scroll,
+  window/level, flips, rotation, tags, and cine playback.
+- Load, edit, and export rectangular ROI annotations without modifying the
+  source DICOM files.
+- Use the same tool from a shell command, a Python script, or a notebook.
+- Run as an ephemeral server with no database, config file, or persistent state.
+
+## Install
+
+On supported Linux platforms, the Python package bundles the `dcmview` binary:
+
+```bash
+python -m pip install --user dcmview-py
+dcmview --help
+```
+
+The package installs both `dcmview` and `dcmview-py`; `dcmview` is the primary
+command.
+
+On macOS, use the published Homebrew tap or download a prebuilt archive from
+GitHub Releases.
+
+Source builds are available for contributors and unsupported platforms:
+
+```bash
+cargo install --path .
+```
+
+Build prerequisites for source installs:
+
+- Rust stable 1.75+
+- Node.js 18+ and npm at build time
+- `ssh` on `PATH` only when using SSH forwarding helpers
+
+## Quick Start
+
+Open one file:
+
+```bash
+dcmview ./scan.dcm
+```
+
+Scan a study directory recursively:
+
+```bash
+dcmview ./study_dir
+```
+
+Run without opening a browser, useful on a remote server:
+
+```bash
+dcmview --no-browser ./study_dir
+```
+
+When ready, `dcmview` prints a URL:
+
+```text
+dcmview: server running at http://127.0.0.1:<port>
+```
+
+Press Ctrl+C to stop the server.
+
+## Remote Server Workflow
+
+The safest default is to keep `dcmview` bound to loopback on the remote machine
+and access it through SSH port forwarding.
+
+On the remote server:
+
+```bash
+dcmview --no-browser --port 8888 /path/to/dicom_or_study_dir
+```
+
+On your local machine:
+
+```bash
+ssh -L 8888:localhost:8888 user@remote-server
+```
+
+Then open:
+
+```text
+http://localhost:8888
+```
+
+You can also let `dcmview` use an auto-assigned port by omitting `--port`; copy
+the printed port into your SSH command. The optional `--tunnel` flags are
+available for environments where the `dcmview` process can start the SSH helper
+itself.
+
+The HTTP server is unauthenticated. It binds to `127.0.0.1` by default. If you
+bind to `0.0.0.0` or another public interface, use your own network access
+controls.
+
+## Python Usage
+
+`dcmview-py` is a small subprocess wrapper around the Rust binary. It is useful
+when a script or notebook has already selected the cases to inspect.
+
+```python
+from dcmview_py import view
+
+# Blocking call; returns when dcmview exits.
+view(["./scan.dcm"], browser=False, timeout=300)
+
+# Non-blocking call.
+handle = view(["./study_dir"], browser=False, block=False)
+print(handle.url)
+handle.stop()
+```
+
+Context manager:
+
+```python
+from dcmview_py import view
+
+with view(["./study_dir"], browser=False, block=False) as handle:
+    print(handle.url)
+```
+
+The module CLI mirrors the Rust options:
+
+```bash
+python -m dcmview_py --no-browser --timeout 120 ./study_dir
+```
+
+## Viewer Features
+
+The embedded browser viewer includes:
+
+- File tabs labeled from `PatientID`, `Modality`, and `StudyDate` when present.
+- Canvas-based image viewing with pan, zoom, scroll, window/level, reset,
+  horizontal/vertical flips, and 90-degree rotation.
+- Window presets including DICOM defaults, full dynamic range, and common CT
+  presets.
+- Multi-frame controls with previous/next, cine playback, FPS selection, loop,
+  and sweep.
+- Lazy DICOM tag browsing with filtering, sequence expansion, binary length
+  display, resizable columns, and click-to-copy values.
+- Rectangular ROI annotation display and editing, including draw, select, move,
+  resize, delete, frame scoping, and CSV export.
+
+Common shortcuts:
+
+| Action | Shortcut |
+|---|---|
+| Previous/next frame | Left/Right arrows or `[` / `]` |
+| Play/pause cine | Space |
+| Window/level tool | `W` |
+| Pan tool | `P` |
+| Zoom tool | `Z` |
+| Scroll tool | `S` |
+| ROI tool | `R` |
+| Reset viewport | Double-click |
+
+Right-drag always zooms, middle-drag always pans, the wheel scrolls frames, and
+Ctrl/Cmd+wheel zooms.
+
+## Annotations
+
+`--annotations` loads an EMBED-style ROI CSV into memory:
+
+```bash
+dcmview --annotations ./embed_annotations.csv ./study_dir
+```
+
+`dcmview` never modifies the input CSV or DICOM files. Viewer edits are kept in
+memory and can be downloaded with **Export ROIs**.
+
+Required columns:
+
+- `anon_dicom_path`
+- `ROI_coords`
+
+Optional columns:
+
+- `num_ROI`; when present, it must equal `len(ROI_coords)`
+- `ROI_frames`; when omitted or `[]`, ROIs apply to all frames
+
+`ROI_coords` is a JSON array of `[ymin, xmin, ymax, xmax]` boxes. `ROI_frames`
+is a JSON array of frame-index lists. JSON-valued fields must be CSV-quoted.
+
+```csv
+anon_dicom_path,num_ROI,ROI_coords,ROI_frames
+/path/to/dbt_case.dcm,2,"[[120,340,220,430],[400,510,480,590]]","[[0,1,2],[5,6]]"
+/path/to/ffdm_case.dcm,1,"[[80,150,190,260]]","[]"
+```
+
+Matching uses normalized path equality against loaded DICOM paths. Frame indices
+are zero-based and must be less than `NumberOfFrames`.
+
+## CLI Reference
+
+```text
+dcmview [OPTIONS] <PATH> [PATH ...]
+```
+
+| Option | Default | Description |
+|---|---:|---|
+| `<PATH>...` | required | DICOM files or directories to inspect |
+| `-p, --port <u16>` | `0` | Bind port; `0` auto-assigns an available port |
+| `--host <addr>` | `127.0.0.1` | Bind address |
+| `--no-browser` | false | Do not open the browser automatically |
+| `--timeout <seconds>` | none | Exit after this many seconds without API/browser requests |
+| `--no-recursive` | false | Scan only the top level of input directories |
+| `--tunnel` | false | Start an SSH local port-forward helper |
+| `--tunnel-host <host>` | none | SSH target used with `--tunnel` |
+| `--tunnel-port <u16>` | `0` | Forwarded local port; `0` uses the server port |
+| `--annotations <csv>` | none | Load EMBED-style ROI annotations |
+
+Examples:
+
+```bash
+dcmview ./scan.dcm
+dcmview --no-recursive ./study_dir
+dcmview --host 127.0.0.1 --port 8888 --no-browser ./study_dir
+dcmview --timeout 300 ./study_dir
+dcmview --annotations ./embed_annotations.csv ./study_dir
+```
+
+## HTTP API
+
+The browser UI uses a small local HTTP API. It is also useful for scripts that
+need the same decoded frame, tag, or annotation data while the server is running.
+
+Static frontend assets are served at `/` and `/assets/*`.
+
+| Method | Path | Description |
+|---|---|---|
+| GET | `/api/health` | Ready-state probe with file count and server start time |
+| GET | `/api/files` | File registry and server metadata |
+| GET | `/api/file/:index/info` | Frame metadata for one file |
+| GET | `/api/file/:index/frame/:frame` | Display frame; supported image transfer syntaxes return PNG |
+| GET | `/api/file/:index/frame/:frame/raw` | Decoded frame sample bytes for client-side rendering |
+| GET | `/api/file/:index/tags` | Lazy DICOM tag tree |
+| GET | `/api/file/:index/annotations` | Current in-memory ROI annotations |
+| PUT | `/api/file/:index/annotations` | Replace in-memory ROI annotations for one file |
+| GET | `/api/annotations/export.csv` | Download current annotations as EMBED CSV |
+
+### Health and Files
+
+`GET /api/health` returns:
+
+```json
+{
+  "status": "ok",
+  "file_count": 2,
+  "server_start_ms": 1714300000000
+}
+```
+
+`GET /api/files` returns:
+
+```json
+{
+  "files": [
+    {
+      "index": 0,
+      "path": "/path/to/scan.dcm",
+      "label": "PATIENT - MG - 20240101",
+      "has_pixels": true,
+      "frame_count": 60,
+      "rows": 3000,
+      "columns": 2500,
+      "transfer_syntax_uid": "1.2.840.10008.1.2.4.50",
+      "default_window": { "center": 200.0, "width": 4000.0 }
+    }
+  ],
+  "tunnelled": false,
+  "tunnel_host": null,
+  "server_start_ms": 1714300000000
+}
+```
+
+`GET /api/file/:index/info` returns `frame_count`, `rows`, `columns`,
+`transfer_syntax`, `has_pixels`, and `default_window`.
+
+### Display Frames
+
+`GET /api/file/:index/frame/:frame` returns `image/png` for supported display
+paths.
+
+Query parameters:
+
+| Param | Description |
+|---|---|
+| `wc` | Window center; used with `ww` in default mode |
+| `ww` | Window width; used with `wc` in default mode |
+| `mode` | `default` or `full_dynamic` |
+
+Window selection:
+
+- `default`: explicit `wc` and `ww`, then DICOM Window Center/Width, then
+  1st/99th percentile fallback.
+- `full_dynamic`: true min/max of the current frame; ignores DICOM defaults and
+  query window values.
+
+Transfer syntax behavior:
+
+| Transfer syntax | Display behavior |
+|---|---|
+| JPEG Baseline / Extended | Decoded server-side and PNG-encoded |
+| JPEG Lossless / Lossless SV1 | Decoded server-side and PNG-encoded |
+| JPEG 2000 lossless/lossy | Decoded server-side and PNG-encoded |
+| Implicit LE / Explicit LE / Explicit BE | Windowed server-side and PNG-encoded |
+| JPEG-LS / RLE / other | `422 {"error": "unsupported transfer syntax: ..."}` |
+
+Response headers include `X-Cache: HIT` or `X-Cache: MISS`.
+
+### Raw Frames
+
+`GET /api/file/:index/frame/:frame/raw` returns `application/octet-stream` plus
+metadata headers. This is a decoded sample transport for the frontend, not a
+copy of the original DICOM Pixel Data element for compressed syntaxes.
+
+Supported raw paths:
+
+- Uncompressed frames: native sample bytes, normalized to little-endian by
+  `dicom-object`.
+- JPEG Baseline / Extended: decoded to 8-bit grayscale samples.
+- JPEG Lossless: decoded to 8-bit or 16-bit grayscale samples when supported by
+  the codec stack.
+- Grayscale JPEG 2000: decoded to 8-bit or 16-bit samples.
+
+JPEG-LS, RLE, unsupported syntaxes, and multi-component JP2 raw decoding return
+422 or a decode error.
+
+### Tags and Annotations
+
+`GET /api/file/:index/tags` returns an array of DICOM tag nodes. Pixel data and
+other binary VRs are represented by byte length, not by full values. Long
+numeric arrays and sequences may be truncated with `truncated` and `total`
+fields.
+
+`GET /api/file/:index/annotations` returns:
+
+```json
+{
+  "num_roi": 2,
+  "roi_coords": [[120, 340, 220, 430], [400, 510, 480, 590]],
+  "roi_frames": [[0, 1, 2], [5, 6]]
+}
+```
+
+`PUT /api/file/:index/annotations` replaces one file's in-memory annotations and
+returns the canonicalized payload. Invalid coordinates or frame mappings return
+`400 {"error": "..."}`.
+
+## Development
+
+Frontend:
+
+```bash
+npm --prefix frontend ci
+dcmview --no-browser --host 127.0.0.1 --port 8888 tests/fixtures
+npm --prefix frontend run dev
+npm --prefix frontend run build
+```
+
+The Vite dev server proxies `/api` to `http://127.0.0.1:8888`, so start a
+backend on that host and port before using the standalone frontend dev server.
+
+Backend:
+
+```bash
+cargo fmt --all
+cargo fmt --all -- --check
+cargo check
+cargo build
+cargo build --release
+```
+
+Tests:
+
+```bash
+cargo test
+```
+
+Integration tests use real DICOM fixtures and cover discovery, display-frame
+decoding, raw-frame transport, cache headers, tag serialization, annotations,
+and tunnel fallback.
+
+Architecture summary:
+
+- Backend: Rust, Axum, Tokio
+- DICOM: `dicom-rs`, `dicom-pixeldata`, `jpeg2k`
+- Pixel pipeline: server-side display PNGs, raw sample transport for
+  interactive rendering, LRU caches
+- Frontend: Svelte 5, Vite, TypeScript, embedded via `rust-embed`
+- Distribution: one executable with no runtime frontend assets
+
+Backend frame cache budgets are currently 256 MiB for display PNGs and 384 MiB
+for raw sample frames. The frontend also keeps active frame blobs, raw buffers,
+and rendered bitmaps in memory for responsiveness, so cache budget changes
+should consider total browser plus server memory pressure.
+
+## License
+
+MIT

dcmview_py-0.2.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+dcmview_py/__init__.py,sha256=T3u48aRHRGNpbXK1jWKmmP-K14qwaJZbjKWbfzxBld0,138
+dcmview_py/__main__.py,sha256=PEqmFmXg9r_Uf-fX8tNuaE3T6pOdbtH-3SQeXW16Urg,2183
+dcmview_py/wrapper.py,sha256=ckOm_KaL3aRdFv7qUOIHMrVUaFEubsxtLvT6s-aOI9Q,12542
+dcmview_py/bin/dcmview.exe,sha256=6HqAQE95QNPZDyFGYSyXVwoyQlfMfb4HPSbVgga-nhY,12989952
+dcmview_py-0.2.2.dist-info/licenses/LICENSE,sha256=mTvPbRX_DTDxgsWVdcjAAARlsBCdYE-ITOwubz9p8dg,1098
+dcmview_py-0.2.2.dist-info/METADATA,sha256=aymtb6NFIZCVQbwy6VzJ5EMKqZB8yACDApAIT-b1Mzk,13403
+dcmview_py-0.2.2.dist-info/WHEEL,sha256=GjDPPQwEcripVP6P2r3RxLa-h5Lb9ifGB7FYYtbLDT0,98
+dcmview_py-0.2.2.dist-info/entry_points.txt,sha256=Gb1QTe6yv_jHX-GIONDYUo2KAYtgeGcesRffPpKxRYY,91
+dcmview_py-0.2.2.dist-info/top_level.txt,sha256=OBCmc-D0FYpXs3BzBqDGTxteXYJnpTNyr4Ickd7wEuo,11
+dcmview_py-0.2.2.dist-info/RECORD,,

dcmview_py-0.2.2.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: false
+Tag: py3-none-win_amd64
+

dcmview_py-0.2.2.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dcmview = dcmview_py.__main__:main
+dcmview-py = dcmview_py.__main__:main

dcmview_py-0.2.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Beatrice Brown-Mulry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dcmview_py-0.2.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+dcmview_py