npm package: @holoscript/medical-plugin
Description: DICOM medical imaging and surgical simulation for HoloScript - VR medical training
Author: HoloScript Contributors
Latest version: 1.0.0

# @holoscript/medical-plugin

**DICOM medical imaging and surgical simulation for HoloScript - VR medical training and visualization**

[![npm version](https://badge.fury.io/js/%40holoscript%2Fmedical-plugin.svg)](https://www.npmjs.com/package/@holoscript/medical-plugin)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

## Features

### 🏥 DICOM Visualization (`@dicom_viewer`)
- **CT/MRI/PET imaging** in VR
- **Slice navigation** (axial, sagittal, coronal)
- **3D volume rendering** with window/level control
- **MPR (Multi-Planar Reconstruction)**
- **Color maps**: grayscale, bone, hot, cool, PET

### ⚕️ Surgical Planning (`@surgical_plan`)
- **Pre-operative planning** tools
- **Implant positioning** (arthroplasty, cranial plates)
- **Cutting planes** for resection planning
- **Safety margins** around critical structures
- **Multi-surgeon collaboration** in VR
- **Export to surgical navigation** (StealthStation, BrainLab)

### 🧠 Anatomical Education (`@anatomical_model`)
- **Interactive 3D anatomy** (heart, brain, skeleton, organs)
- **Layer visibility** (skin, muscle, bones, organs, vascular, nervous)
- **Animated systems** (heartbeat, breathing, blood flow)
- **Educational quizzes** with voice narration
- **Multi-language labels**

### 🎯 Medical Simulation (`@medical_simulation`)
- **Procedural training** (CPR, intubation, suturing, IV insertion, laparoscopy)
- **Haptic feedback** (realistic resistance, vibration)
- **Realtime assessment** (technique, speed, accuracy)
- **Patient vitals simulation**
- **Session recording** for review

## Installation

```bash
npm install @holoscript/medical-plugin
```

### Python Dependencies

```bash
pip install pydicom numpy scikit-image
```

## Quick Start

### DICOM CT Scan Viewer

```holoscript
scene "Radiology Workstation" {
  background: "#1a1a2e";
  lighting: "medical_bright";
}

object "Brain CT" @dicom_viewer @grabbable {
  source: "dicom://path/to/ct_series";
  mode: "3d_volume";

  windowLevel: {
    center: 40;
    width: 80;
  };

  colorMap: "bone";
  position: [0, 1.5, -2];
}
```

### Surgical Planning

```holoscript
object "Hip Replacement" @surgical_plan @collaborative {
  anatomy: "dicom://patient_123/ct_pelvis";
  procedure: "arthroplasty";

  tools: {
    implant: {
      model: "implants/hip_cup_54mm.obj";
      position: [0.02, 0.15, -0.05];
      rotation: [15, 20, 5];
    };
    measure: true;
  };

  export: {
    format: "stealthstation";
    path: "exports/plan_patient123.json";
  };
}
```

### Anatomical Model

```holoscript
object "Heart" @anatomical_model @animated {
  anatomy: "heart";
  detail: "high_detail";

  labels: {
    enabled: true;
    detail: "medical_terms";
  };

  animation: {
    type: "heartbeat";
    speed: 1.0;  // 60 BPM
  };

  educational: {
    quiz: true;
    voiceNarration: true;
  };
}
```

### Medical Simulation

```holoscript
object "CPR Mannequin" @medical_simulation @haptic {
  type: "cpr";

  haptics: {
    enabled: true;
    resistance: 0.7;
    vibration: true;
  };

  assessment: {
    enabled: true;
    criteria: ["depth", "rate", "hand_position"];
    realtime_feedback: true;
  };

  vitals: {
    heartRate: 0;  // Cardiac arrest
  };
}
```

## Traits

| Trait | Description |
|-------|-------------|
| `@dicom_viewer` | DICOM medical imaging visualization (CT, MRI, PET) |
| `@surgical_plan` | Pre-operative surgical planning tools |
| `@anatomical_model` | Interactive 3D anatomical models for education |
| `@medical_simulation` | Procedural training simulations with haptics |

## Examples

See `examples/` directory:
- `medical-imaging.holo` - DICOM visualization, surgical planning, anatomy, simulations

## Python Bridge

The plugin includes a Python bridge (`python/dicom_bridge.py`) for DICOM processing:

```typescript
import { MedicalPythonBridge } from '@holoscript/medical-plugin';

const bridge = new MedicalPythonBridge();

// Load DICOM file
const metadata = await bridge.loadDICOM('path/to/scan.dcm');

// Apply window/level
const windowed = await bridge.applyWindowLevel({ center: 40, width: 80 });

// Extract 3D volume from series
const volume = await bridge.extract3DVolume('path/to/series/');
```

## Use Cases

- **Radiology**: CT/MRI/PET review in VR
- **Surgical Planning**: Pre-operative rehearsal and implant positioning
- **Medical Education**: Interactive anatomy training
- **Telemedicine**: Remote collaboration on medical imaging
- **Research**: Scientific visualization of medical data
- **Simulation Training**: Procedural skills without patients

## DICOM Support

**Supported modalities**: CT, MRI, PET, X-Ray, Ultrasound

**Supported formats**: DICOM (.dcm), NIfTI (.nii), NRRD

## Requirements

- **Node.js**: ≥18.0.0
- **Python**: ≥3.8 (for DICOM processing)
- **HoloScript**: ^3.1.0

## License

MIT © HoloScript Contributors

## Contributing

Issues and PRs welcome at [holoscript/holoscript-medical-plugin](https://github.com/holoscript/holoscript-medical-plugin)

## Citation

If you use this plugin in research, please cite:

```bibtex
@software{holoscript_medical_plugin,
  title={HoloScript Medical Plugin: DICOM Visualization and Surgical Planning in VR},
  author={HoloScript Contributors},
  year={2026},
  url={https://github.com/holoscript/holoscript-medical-plugin}
}
```