# InSono - Ultrasound Research & Image Processing

## Overview

InSono is a medical research application for ultrasound image processing. It provides tools for processing medical imaging files including DICOM, PNG, and JPG formats. The application features image processing capabilities like Gaussian blur and CLAHE contrast adjustment, with a focus on patient privacy and research workflows.

## Recent Changes (February 2026)

### Batch Processing Feature
- **Mode Toggle**: Tab switcher between "Single Image" and "Batch Processing" modes
- **Batch Upload**: Multi-file drag-and-drop, up to 50 files per batch
- **AI Quality Scoring**: Weighted formula (40% sharpness, 30% contrast, 30% SNR) produces 0-100 score
- **Smart Filtering**: Quality threshold slider, Top 10/20 presets, visual Included/Excluded lists
- **Multi-Step Enhancement Pipeline**: Three modes - Auto Optimize, Guided, Custom
  - **Auto Optimize**: Tests 12 conservative parameter combinations for natural-looking results (batch mode)
  - **Guided**: Three philosophies (Subtle, Balanced, Aggressive) with conservative parameter ranges, Aggressive capped at CLAHE 4.0
  - **Custom**: Full manual control with enable/disable toggles for each step (Denoise, CLAHE, Sharpen)
- **Pipeline Order**: Always Denoise -> CLAHE -> Sharpen (critical for quality)
- **Enhancement Tracking**: Per-image enhancement_params, quality_history (per-step scores), quality_improvement
- **Statistics Panel**: Average improvement, contribution breakdown (Denoising avg, CLAHE avg, Sharpening avg)
- **Dual PDF Export**: "PDF Selected" (filtered) and "PDF All" options, server-side ReportLab generation with pipeline details
- **Backend Endpoints**: /api/batch-upload, /api/batch-process (mode param), /api/filter-batch, /api/batch-report
- **Storage**: In-memory batch_storage dict keyed by batch_id
- **Note**: Blur removed from batch processing (counter-productive for enhancement goals); blur remains in single-image mode

### PDF Report Generation
- **Single Image**: Client-side jsPDF with header, images (aspect-ratio preserved), metadata, quality analysis, settings, footer
- **Batch Report**: Server-side ReportLab with summary page, quality ranking table, per-image pages with original/processed comparison and metrics

### Single Image Enhancement Pipeline (aligned with batch processing)
- **Enhancement Mode Selector**: Radio buttons to toggle Quick Enhancement, AI Segmentation, or Advanced mode
- **Quick Enhancement**: Fixed medical-grade pipeline: SRAD Denoising (3 iterations, gentle) -> CLAHE (clipLimit=2.0, tileGrid=8x8) -> Unsharp Mask (alpha=1.5, beta=-0.5)
- **AI Segmentation**: MONAI UNet + intensity-based region growing (replaced MedSAM2)
  - **MONAI UNet**: Lightweight 2D UNet (16-32-64-128-256 channels, ~50MB) for medical image segmentation
  - **Hybrid approach**: UNet probability map (30% weight) combined with click-based region growing (70% weight)
  - User clicks on image to segment anatomical regions
  - Cyan semi-transparent overlay (0.25 opacity) with bright yellow contour outline on detected structures
  - Multimask output: 3 mask sizes (Tight/Medium/Wide) via different thresholds
  - Mask size selector UI: purple buttons to switch between mask sizes without re-segmenting
  - Fallback: pure region growing with multiple tolerance levels if combined masks are empty
  - Post-processing: morphological open/close cleanup
  - Backend: /api/ai-segment returns all 3 masks, /api/ai-segment-select switches between stored masks
  - Backend: /api/segmentation-status returns MONAI availability and RAM info
  - In-memory segmentation_storage dict for mask switching
  - Download segmented result as PNG
  - **Architecture**: models/ directory with monai_inference.py, utils/ for shared functions
  - **No checkpoint downloads**: Model initializes from scratch in ~1-2 seconds, no external files needed
- **Advanced Mode**: Manual control with three pipeline steps (Denoise, CLAHE, Sharpen)
  - Each step has enable/disable toggle and strength controls
  - Denoising: Light/Medium/Strong radio buttons
  - CLAHE: Clip limit slider (0.5-5.0) with preset buttons (Subtle 1.5, Standard 2.5, Strong 3.5)
  - Sharpening: Light/Medium/Strong radio buttons
- **Pipeline Order**: Always Denoise -> CLAHE -> Sharpen (same as batch mode)
- **Enhancement Pipeline Results**: Step-by-step quality progression with color-coded deltas
- **Processed Label**: Updates to "Enhanced (Auto-optimized)" or "Enhanced (details)" based on mode
- **PDF Export**: Updated to show enhancement mode and pipeline settings instead of old blur/CLAHE
- **State Simplified**: Removed old blurAmount, claheEnabled, claheClipLimit, pseudonymize state fields
- **Backend**: /api/process accepts mode='quick', mode='advanced' (backward compatible)
- **Blur Removed**: Single-image mode no longer has Gaussian blur (aligned with batch processing)

### Session History Feature
- **Location**: Collapsible panel at bottom of page
- **Storage**: Browser sessionStorage (client-side only, clears on browser close)
- **Max entries**: 50 per session
- **Tracks**: Thumbnail (100x100), filename, timestamp, enhancement mode, pseudonymized, quality score
- **Actions**: View (scroll to result), Re-process (load with reset settings), Download
- **Export**: CSV format (Filename, Timestamp, Enhancement_Mode, Pseudonymized, Sharpness_Score)
- **Best quality highlight**: Green border on highest quality entry when 2+ entries exist
- **Responsive**: Table view on desktop, card view on mobile

### Image Quality Analysis
- **Sharpness Score**: 0-100 using Laplacian variance method
- **Contrast Ratio**: std/mean calculation
- **SNR**: 20*log10(mean/std) in dB
- **Color-coded ratings**: Excellent (green, 80+), Good (yellow, 60-79), Fair (orange, 40-59), Poor (red, 0-39)
- **Quality improvement badges**: Shows changes after processing

## User Preferences

Preferred communication style: Simple, everyday language.

## System Architecture

### Frontend Architecture
- **Framework**: React with TypeScript using Vite as the build tool
- **Routing**: Wouter for client-side routing
- **State Management**: TanStack React Query for server state and data fetching
- **UI Components**: shadcn/ui component library built on Radix UI primitives
- **Styling**: Tailwind CSS with custom design tokens for medical-themed UI
- **Design System**: Material Design Medical Variant with Inter font for readability and JetBrains Mono for technical data

### Backend Architecture
- **Dual Server Setup**: Express.js (Node.js) server that proxies API requests to a Flask (Python) backend
- **API Proxy Pattern**: Express handles static files and routes `/api` requests to Flask running on port 5001
- **Image Processing**: Python/Flask backend using OpenCV, NumPy, and pydicom for medical image manipulation
- **File Handling**: Multer-style uploads with 50MB file size limit, supporting PNG, JPG, JPEG, and DICOM formats

### Data Storage
- **Database**: PostgreSQL with Drizzle ORM for schema management
- **Schema Location**: `shared/schema.ts` contains database models
- **Current Schema**: Basic user authentication table (users with id, username, password)
- **In-Memory Fallback**: MemStorage class provides in-memory storage when database is unavailable

### Build and Development
- **Development**: `npm run dev` runs Express server with Vite middleware for hot reloading
- **Production Build**: esbuild bundles server code, Vite builds client to `dist/public`
- **Database Migrations**: Drizzle Kit with `npm run db:push` for schema synchronization

## External Dependencies

### Segmentation Architecture (models/ directory)
- **models/__init__.py**: MONAI UNet router with structured error responses
- **models/monai_inference.py**: MONAI UNet inference (hybrid: 30% UNet + 70% region growing)
- **utils/image_processing.py**: Shared functions (postprocess_mask, parse_mask_data, render_overlay)
- **No checkpoint downloads**: Model initializes from scratch in ~1-2 seconds, no external files needed

### Python Libraries (Flask Backend)
- **Flask**: Web framework for image processing API
- **OpenCV (cv2)**: Image processing and manipulation
- **NumPy**: Numerical operations for image arrays
- **pydicom**: DICOM medical image file parsing
- **PIL/Pillow**: Additional image format support
- **psutil**: System resource monitoring (RAM checks for model loading)
- **PyTorch**: Deep learning framework for local segmentation models (CPU-only)

### Node.js Services
- **PostgreSQL**: Primary database (requires DATABASE_URL environment variable)
- **http-proxy-middleware**: Routes API requests from Express to Flask backend

### Frontend Libraries
- **Radix UI**: Accessible component primitives
- **TanStack React Query**: Data fetching and caching
- **Recharts**: Chart visualization (via shadcn/ui chart component)
- **react-hook-form**: Form state management with zod validation