PATHORA_VIEWER_README.md

# Pathora Viewer - Whole Slide Image Viewer

A QuPath-inspired web-based image viewer built with OpenSeadragon for viewing and annotating pathology slides.

## Features

### Layout
- **Left Sidebar**: Tool palette with interactive buttons
- **Central Viewer**: OpenSeadragon-powered image viewer with deep zoom capabilities
- **Top Toolbar**: Slide information, zoom controls, and overlay toggles
- **Navigator**: Minimap in bottom-right corner for quick navigation

### Tools
1. **Select Tool**: Click to select and interact with annotations
2. **Pan Tool**: Navigate around the slide (default)
3. **Rectangle Tool**: Draw rectangular regions of interest
4. **Polygon Tool**: Draw freeform polygonal annotations

### Toolbar Features
- **Slide Name**: Displays the current slide being viewed
- **Zoom Level**: Real-time zoom indicator (e.g., 1.50x)
- **Reset View**: Return to the home/default view
- **Zoom In/Out**: Buttons to control magnification
- **Annotations Toggle**: Show/hide annotation overlays
- **Heatmap Toggle**: Show/hide AI-generated heatmap overlays

### Navigation
- **Pan**: Click and drag with pan tool or middle mouse button
- **Zoom**: Mouse wheel or zoom buttons
- **Double-click**: Quick zoom to clicked area
- **Navigator**: Click minimap to jump to location

## Technical Details

### Technologies Used
- **React**: Component-based UI framework
- **TypeScript**: Type-safe development
- **OpenSeadragon**: Deep zoom image viewer
- **Tailwind CSS**: Modern, responsive styling
- **Lucide React**: Clean, consistent icons
- **React Router**: Client-side routing

### Component Structure
```
viewer/
├── PathoraViewer.tsx      # Main viewer component
├── ToolsSidebar.tsx       # Left tool palette
├── TopToolbar.tsx         # Top control bar
├── viewer.css             # Custom styles
└── index.ts               # Exports
```

### OpenSeadragon Configuration
- **Deep Zoom**: Supports multi-resolution tile pyramids
- **Navigator**: Enabled with custom styling
- **Constraints**: Prevents panning outside image bounds
- **Gestures**: Customized mouse interactions

## Usage

### Accessing the Viewer
1. From the main dashboard, click **"Pathora Viewer"** in the sidebar
2. Or navigate directly to `/viewer` route

### Basic Workflow
1. **Open a slide**: Currently loads sample images (can be extended to file upload)
2. **Select a tool**: Click a tool button in the left sidebar
3. **Interact with the image**:
   - Use pan tool to navigate
   - Use drawing tools to annotate regions
4. **Adjust overlays**: Toggle annotations and heatmap as needed
5. **Reset view**: Click "Reset View" to return to starting position

### Keyboard Shortcuts (Future Enhancement)
- `Space + Drag`: Temporary pan
- `+/-`: Zoom in/out
- `H`: Toggle heatmap
- `A`: Toggle annotations
- `Esc`: Deselect tool

## Customization

### Loading Custom Images
Edit the `PathoraViewer` component props:
```tsx
<PathoraViewer 
  imageUrl="/path/to/your/image.jpg"
  slideName="Your Slide Name.svs"
/>
```

### Adding Deep Zoom Tiles
For large whole slide images, use DZI (Deep Zoom Image) format:
```tsx
tileSources: {
  type: "image",
  url: "/path/to/image.dzi"
}
```

### Styling
Modify colors and appearance in:
- `viewer.css`: OpenSeadragon-specific styles
- Component files: Tailwind classes for UI elements

## Future Enhancements

### Planned Features
- [ ] File upload for custom slides
- [ ] Persistent annotation storage
- [ ] Measurement tools (ruler, area)
- [ ] Annotation export (JSON, GeoJSON)
- [ ] Collaborative viewing/annotations
- [ ] AI model integration for auto-annotation
- [ ] Multi-channel fluorescence support
- [ ] Z-stack navigation for 3D images
- [ ] Annotation categories/classification
- [ ] Export annotated regions as images

### Advanced Features
- [ ] Integration with DICOM WSI
- [ ] Server-side tile generation
- [ ] Real-time collaboration
- [ ] Pathologist reporting tools
- [ ] Machine learning overlay visualization
- [ ] Comparison mode (side-by-side slides)

## Medical Imaging Standards

The viewer is designed with pathology workflows in mind:
- Compatible with common WSI formats (SVS, NDPI, TIFF)
- Optimized for high-resolution microscopy images
- Follows QuPath-inspired UX patterns familiar to pathologists

## Development

### Running the Viewer
```bash
cd frontend
npm install
npm run dev
```

Navigate to `http://localhost:5173/viewer`

### Building for Production
```bash
npm run build
```

## License
Part of the Pathora medical imaging platform.

---

**Note**: This viewer is designed for research and educational purposes. For clinical diagnostic use, ensure compliance with relevant medical device regulations and standards.