306 lines
8.4 KiB
Markdown
306 lines
8.4 KiB
Markdown
# RTX Digital Twin - Medical Digital Twin Platform
|
||
|
||
A patient-specific organ simulation framework combining physics-based models for thermal therapy planning and treatment optimization.
|
||
|
||
## Overview
|
||
|
||
This crate provides a complete Medical Digital Twin Platform for:
|
||
- Creating patient-specific organ geometry from medical imaging segmentation
|
||
- Physics-based simulation (Pennes bioheat equation for thermal ablation)
|
||
- Intervention modeling (RFA, microwave, HIFU, laser ablation)
|
||
- What-if analysis for treatment planning
|
||
- Real-time thermal damage prediction
|
||
|
||
## Architecture
|
||
|
||
```
|
||
Medical Images (CT/MRI)
|
||
↓
|
||
Segmentation → Tissue Labels
|
||
↓
|
||
Organ Geometry (3D voxel grid with tissue properties)
|
||
↓
|
||
Physics Model (bioheat equation with perfusion)
|
||
↓
|
||
Digital Twin (simulation engine)
|
||
↓
|
||
What-If Analysis → Treatment Planning
|
||
```
|
||
|
||
## Key Features
|
||
|
||
### 1. Patient-Specific Geometry
|
||
- Voxel-based 3D representation from segmentation
|
||
- Multi-tissue support (16+ tissue types)
|
||
- Physical properties database (thermal, mechanical, electrical)
|
||
- Automatic property field generation
|
||
|
||
### 2. Physics Simulation
|
||
- **Pennes Bioheat Equation**: Accounts for blood perfusion and metabolic heat
|
||
- **Steady-state solver**: Gauss-Seidel iterative method
|
||
- **Transient solver**: Explicit finite difference time stepping
|
||
- **Thermal damage**: CEM43 equivalent dose calculation
|
||
|
||
### 3. Intervention Modeling
|
||
- **Ablation Probes**: RFA, microwave, laser
|
||
- **HIFU**: Focused ultrasound with Gaussian beam model
|
||
- Customizable heat source distributions
|
||
- Active/inactive control
|
||
|
||
### 4. Treatment Planning
|
||
- Multiple scenario comparison
|
||
- Safety margin analysis
|
||
- Damage volume prediction
|
||
- Clinical report generation
|
||
|
||
## Quick Start
|
||
|
||
### Basic Usage
|
||
|
||
```rust
|
||
use rtx_digital_twin::{
|
||
AblationProbe, DigitalTwin, OrganGeometry, TissueType, TissueLabel,
|
||
};
|
||
|
||
// Create geometry from segmentation
|
||
let mut geometry = OrganGeometry::new([30, 30, 30], [1.0, 1.0, 1.0]);
|
||
|
||
// Fill with liver tissue
|
||
for z in 5..25 {
|
||
for y in 5..25 {
|
||
for x in 5..25 {
|
||
geometry.set_label(x, y, z, TissueLabel::from(TissueType::Liver));
|
||
}
|
||
}
|
||
}
|
||
|
||
// Add tumor
|
||
geometry.create_sphere([15.0, 15.0, 15.0], 4.0, TissueLabel::from(TissueType::Tumor));
|
||
|
||
// Create digital twin
|
||
let mut twin = DigitalTwin::new(geometry);
|
||
|
||
// Plan ablation
|
||
let probe = AblationProbe::new([15.0, 15.0, 15.0], 40.0);
|
||
|
||
// What-if analysis
|
||
let result = twin.what_if(&probe, 60.0)?;
|
||
|
||
println!("Max temp: {:.1}°C", result.max_temperature);
|
||
println!("Damaged volume: {:.1} cm³", result.total_damaged_volume / 1000.0);
|
||
```
|
||
|
||
### Running Examples
|
||
|
||
```bash
|
||
# Simple ablation planning
|
||
cargo run --example simple_ablation
|
||
|
||
# Comprehensive liver tumor ablation planning
|
||
cargo run --example liver_ablation_planning
|
||
```
|
||
|
||
## Core Types
|
||
|
||
### OrganGeometry
|
||
3D voxel grid with tissue labels and physical state at each voxel.
|
||
|
||
```rust
|
||
pub struct OrganGeometry {
|
||
data: Vec<VoxelData>, // Per-voxel data
|
||
shape: [usize; 3], // Grid dimensions
|
||
spacing: [f32; 3], // Voxel size in mm
|
||
origin: [f32; 3], // World coordinates origin
|
||
tissue_db: TissueDatabase, // Tissue properties
|
||
}
|
||
```
|
||
|
||
### DigitalTwin
|
||
Main simulation interface combining geometry, physics, and interventions.
|
||
|
||
```rust
|
||
pub struct DigitalTwin {
|
||
geometry: OrganGeometry,
|
||
config: TwinConfig,
|
||
bioheat: BioheatModel,
|
||
last_result: Option<SimulationResult>,
|
||
}
|
||
```
|
||
|
||
### TissueDatabase
|
||
Physical properties for 16+ human tissue types based on published literature:
|
||
- Thermal: conductivity, specific heat, density
|
||
- Perfusion: blood flow rate, metabolic heat
|
||
- Mechanical: Young's modulus, Poisson ratio
|
||
- Electrical: conductivity, permittivity
|
||
|
||
### Interventions
|
||
Trait-based system for modeling therapeutic interventions:
|
||
|
||
```rust
|
||
pub trait Intervention {
|
||
fn intervention_type(&self) -> InterventionType;
|
||
fn generate_heat_source(&self, geometry: &OrganGeometry) -> Result<Vec<f32>>;
|
||
fn position(&self) -> [f32; 3];
|
||
fn power(&self) -> f32;
|
||
}
|
||
```
|
||
|
||
Implementations:
|
||
- `AblationProbe`: RFA, microwave, laser (cylindrical heat source)
|
||
- `HifuTransducer`: Focused ultrasound (Gaussian beam)
|
||
|
||
## Physics Models
|
||
|
||
### Pennes Bioheat Equation
|
||
|
||
```
|
||
ρc ∂T/∂t = ∇·(k∇T) + ρ_b c_b ω_b (T_b - T) + Q_m + Q_ext
|
||
```
|
||
|
||
Where:
|
||
- `ρ, c`: tissue density and specific heat
|
||
- `k`: thermal conductivity
|
||
- `ρ_b, c_b`: blood density and specific heat
|
||
- `ω_b`: blood perfusion rate [1/s]
|
||
- `T_b`: arterial blood temperature
|
||
- `Q_m`: metabolic heat generation
|
||
- `Q_ext`: external heat source (ablation probe)
|
||
|
||
### Thermal Damage (Arrhenius)
|
||
|
||
Cumulative Equivalent Minutes at 43°C (CEM43):
|
||
```
|
||
damage = ∫ R^(43-T) dt
|
||
```
|
||
|
||
Where R = 0.5 for T > 43°C
|
||
|
||
## Test Coverage
|
||
|
||
### Unit Tests (27 tests)
|
||
- Geometry creation and manipulation
|
||
- Tissue property lookups
|
||
- Coordinate transformations
|
||
- Temperature field operations
|
||
- Physics model configuration
|
||
- Boundary conditions
|
||
- Intervention heat source generation
|
||
|
||
### Integration Tests (13 tests)
|
||
- Complete workflow from segmentation to treatment planning
|
||
- Multi-scenario what-if analysis
|
||
- Transient and steady-state simulations
|
||
- Damage calculation validation
|
||
- Clinical report generation
|
||
|
||
All 40 tests pass with full code coverage of core functionality.
|
||
|
||
## File Structure
|
||
|
||
```
|
||
rtx-digital-twin/
|
||
├── src/
|
||
│ ├── lib.rs # Public API exports
|
||
│ ├── error.rs # Error types (43 lines)
|
||
│ ├── geometry.rs # OrganGeometry (465 lines)
|
||
│ ├── tissue.rs # TissueDatabase (466 lines)
|
||
│ ├── physics.rs # BioheatModel (613 lines)
|
||
│ ├── intervention.rs # Ablation probes, HIFU (385 lines)
|
||
│ └── twin.rs # DigitalTwin API (494 lines)
|
||
├── tests/
|
||
│ └── integration_test.rs # Integration tests (560 lines)
|
||
└── examples/
|
||
├── simple_ablation.rs # Quick demo
|
||
└── liver_ablation_planning.rs # Full workflow
|
||
```
|
||
|
||
All files are well under the 1000-line limit (max: 613 lines).
|
||
|
||
## Dependencies
|
||
|
||
- `rtx-tensor`: Tensor operations
|
||
- `rtx-backend`: Device abstraction
|
||
- `rtx-medical-core`: Volume handling (with `volume` feature)
|
||
- `thiserror`: Error handling
|
||
- `serde`: Serialization
|
||
|
||
## Development Approach
|
||
|
||
This implementation follows strict Test-Driven Development (TDD):
|
||
|
||
1. **RED Phase**: Write failing tests first
|
||
2. **GREEN Phase**: Implement minimal code to pass tests
|
||
3. **REFACTOR Phase**: Clean up while maintaining test passage
|
||
|
||
### TDD Principles Applied
|
||
- No placeholder code or `todo!()` macros
|
||
- Full error handling with `Result<T, E>`
|
||
- Production-ready code from the start
|
||
- State-based testing (no mocks)
|
||
- Comprehensive test coverage
|
||
|
||
## Performance Considerations
|
||
|
||
### Numerical Stability
|
||
- Gauss-Seidel iteration with configurable tolerance
|
||
- Harmonic mean for interface conductivities
|
||
- Explicit time stepping with CFL stability considerations
|
||
|
||
### Grid Resolution
|
||
- Typical: 1mm voxels for clinical accuracy
|
||
- Trade-off: resolution vs. computational cost
|
||
- Recommended: 30³-60³ for real-time planning
|
||
- Research: up to 256³ for detailed analysis
|
||
|
||
### Simulation Time
|
||
- Steady-state: <1 second for 30³ grid
|
||
- Transient (60s physical time): ~2-3 seconds for 30³ grid
|
||
- Scales approximately as O(N) for N voxels
|
||
|
||
## Clinical Applications
|
||
|
||
### Tumor Ablation Planning
|
||
- Liver tumors (HCC, metastases)
|
||
- Kidney tumors
|
||
- Lung nodules
|
||
- Bone lesions
|
||
|
||
### Treatment Optimization
|
||
- Power setting selection
|
||
- Probe positioning
|
||
- Duration planning
|
||
- Safety margin verification
|
||
|
||
### Risk Assessment
|
||
- Thermal damage to adjacent structures
|
||
- Incomplete ablation prediction
|
||
- Heat sink effect analysis
|
||
|
||
## References
|
||
|
||
### Tissue Properties
|
||
- IT'IS Foundation Tissue Properties Database
|
||
- Hasgall et al., "IT'IS Database for thermal and electromagnetic parameters"
|
||
- Duck, F.A., "Physical Properties of Tissues"
|
||
|
||
### Bioheat Transfer
|
||
- Pennes, H.H., "Analysis of tissue and arterial blood temperatures in the resting human forearm" (1948)
|
||
- Weinbaum, S., et al., "A new fundamental bioheat equation for muscle tissue" (1984)
|
||
|
||
### Thermal Damage
|
||
- Sapareto, S.A., Dewey, W.C., "Thermal dose determination in cancer therapy" (1984)
|
||
- Dewhirst, M.W., et al., "Basic principles of thermal dosimetry and thermal thresholds" (2003)
|
||
|
||
## License
|
||
|
||
This project is dual-licensed under MIT OR Apache-2.0.
|
||
|
||
## Contributing
|
||
|
||
Contributions welcome! Please ensure:
|
||
- All tests pass: `cargo test`
|
||
- Code is lint-free: `cargo clippy`
|
||
- Documentation is updated
|
||
- TDD principles are followed
|