Skip to content

About

K-space native detection of neurological pathologies, including microbleeds, invisible in standard reconstructed MRI images. Learns directly from raw MRI frequency-domain data to surface findings that image-based analysis structurally misses.

Topics

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

🧠 MedMatrix (KVISION)

C++ Inference Test Suite SSM Anomaly Test Suite Rust MRI Engine Node.js v20 Python 3.10 License: Apache 2.0

MedMatrix (also known as KVISION) is an enterprise-grade clinical MRI volumetric analysis, k-space anomaly detection, digital brain twin simulation, and automated reporting platform. Built inside a modular pnpm monorepo, it seamlessly couples state-of-the-art Deep Learning (Hybrid S4 State-Space Models + Spatial Convolutions) with high-performance native compute engines (C++ ONNX Runtime and Rust FFT reconstruction) and a Syngo-themed clinical desktop console (Electron + React).


πŸ›οΈ System Architecture & Workflow

MedMatrix operates an automated, two-tier AI cascade to optimize compute budget while ensuring high diagnostic quality on raw multi-coil MRI acquisition streams.

graph TD
    A[DICOM / Raw K-Space Upload] --> B[MinIO S3 Storage: 'kspace-raw']
    B --> C[BullMQ Enqueue Processing Job]
    C --> D[TypeScript Background Worker]
    D --> E[Axios AIServiceClient.predict]
    E --> F[FastAPI /predict Endpoint]
    F --> G[Reconstruct Magnitude Image]
    G --> H[CNN Artifact Classifier]
    H --> I{"Composite score >= 0.5?"}
    
    I -- Yes: Anomaly Detected --> J[Trigger Image Encoder: Motion Correction & Denoising]
    J --> K[Upload reconstructed.npy to 'reconstructed' bucket]
    K --> L[Return full classification scores + report metadata]
    
    I -- No: Clean Scan --> M[Bypass secondary image models to save compute]
    M --> N[Return gating decision: skip image encoder]
    
    L & N --> O[Persist ModelResult, AnomalyDetection & GatingDecision in PostgreSQL via Prisma]
    O --> P[Compile PDF Report draft using Rust Engine]
    P --> Q["Mark Study Status: Complete in Electronic Health Record (EHR)"]
Loading

πŸš€ Key Features

  • ⚑ Two-Tier AI Gating Cascade: Automatically detects hardware artifacts and scan corruption (ghosting, wrap-around, zipper noise) prior to heavy model execution. Clean scans bypass computationally expensive modules to maintain high patient throughput.
  • 🧠 Hybrid Fused S4-CNN Volumetric Classifier: Merges complex-domain frequency sequence analysis (Diagonal State Space Model - S4D) with spatial magnitude slice representations via Slice-Level Cross-Attention. Achieves 88.28% validation accuracy across 11 pathology classes with only ~281k parameters (vs ~67M in traditional 3D CNNs).
  • πŸ“ˆ SSM-Based K-Space Anomaly Estimator: Real-valued diagonal State Space Model reading multi-coil raw complex K-space data row-by-row to predict continuous regression metrics for noise severity, motion blur, and phase corruption.
  • πŸš€ C++ ONNX Runtime Engine: Native C++ executables (kvision::InferenceEngine & kvision::AnomalyDetectorEngine) compiled with CMake and CUDA GPU support, achieving up to 84.8 inferences/second.
  • πŸ¦€ Native Rust MRI Reconstruction & PDF Engine: Phase-corrected 2D centered IFFT slice reconstruction module coupled with a high-speed, native clinical PDF report generator.
  • πŸ’» Syngo-Themed Clinical Desktop App: Electron desktop console adhering to modern clinical Syngo UI design guidelines. Includes raw DICOM ingestion, Cornerstone3D multi-planar viewers, frequency domain k-space visualizers, and Digital Brain Twin node graphs.
  • 🧬 Synthetic Data & Phantom Generation (data-gen): Complete Python simulation suite for generating multi-coil k-space arrays, numerical brain phantoms (PhantomNet), and benchmark pathology datasets.

πŸ“Ί UI/UX Clinical Showcase

1. 3D Volumetric Brain & Lesion Visualizer

Provides interactive 3D mesh renderings overlaying tumor volumes, hemorrhage regions, and lesion nodes using Three.js and VTK.js.

3D Brain Visualizer Interface

2. 2D Clinical Slice Viewer

Multi-planar slice viewer powered by Cornerstone3D, featuring seamless scrolling across axial, sagittal, and coronal slice planes with AI segmentation overlays.

Spatial Domain (Reconstructed MRI Slice)

2D Clinical Slice Viewer Interface

Frequency Domain (Raw K-Space Acquisition)

K-Space Viewer Interface


πŸ—ΊοΈ Monorepo Navigation Dashboard

The MedMatrix repository is organized as a workspace monorepo managed with pnpm.

Med_Matrix/
β”œβ”€β”€ 🐳 docker-compose.yml        <- Infrastructure orchestration (Postgres, Redis, MinIO)
β”œβ”€β”€ πŸ€– ai-service/                <- Python FastAPI + PyTorch AI microservice
β”‚   └── βš™οΈ inference/             <- C++ ONNX Runtime Inference Engine (CMake)
β”œβ”€β”€ πŸ“± apps/
β”‚   β”œβ”€β”€ πŸ–₯️ electron/             <- Electron + React + TypeScript clinical desktop application
β”‚   └── 🌐 backend/              <- Node.js Express server + Prisma ORM + BullMQ worker
β”œβ”€β”€ 🧬 data-gen/                 <- Synthetic MRI & PhantomNet data generator
β”œβ”€β”€ πŸ¦€ rust-mri/                  <- High-speed Rust reconstruction & PDF compiler
└── πŸ“¦ packages/
    β”œβ”€β”€ βš™οΈ config/               <- Shared ESLint, Prettier, and TypeScript configurations
    └── 🧩 shared-types/         <- Shared TypeScript interfaces across client and backend

πŸ—‚οΈ Module Documentation Links:


πŸ› οΈ Installation & Local Development Setup

Prerequisites

  • Node.js: v20+ and pnpm installed globally (npm install -g pnpm)
  • Python: v3.10+ with pip
  • Docker & Compose: For running backing database and storage services
  • C++ Compiler: GCC / Clang, CMake 3.18+, pkg-config
  • Rust: Cargo and rustc (edition 2021)
  • ONNX Runtime C++ Shared Libraries: Installed on host system (e.g. onnxruntime-cuda)

1. Start Backing Infrastructure (Docker)

Launch PostgreSQL, Redis, and MinIO storage containers:

docker-compose up -d

Service ports:

  • PostgreSQL: localhost:5432 (database: medmatrix)
  • Redis: localhost:6379
  • MinIO Console: localhost:9001 (S3 API: localhost:9000)

2. Configure Environment Variables

Copy the root environment template:

cp .env.example .env

Ensure DB, Redis, and MinIO credentials align with your local configuration.


3. Initialize Monorepo & Database Schema

Install Node dependencies and synchronize the Prisma database schema:

pnpm install
cd apps/backend
npx prisma db push
cd ../..

4. Set Up Python AI Microservice

Create a virtual environment and install requirements:

cd ai-service
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

To launch the FastAPI service on port 8000:

uvicorn main:app --reload --host 0.0.0.0 --port 8000

API Documentation will be accessible at http://localhost:8000/docs.


5. Compile C++ ONNX Inference Engine

Build the high-throughput native C++ inference engine:

cd ai-service/inference
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

Run validation unit tests:

./test_inference
./test_anomaly_detector_inference

6. Build Native Rust MRI Engine

Compile the Rust slice reconstruction binary and PDF generator:

cd rust-mri
cargo build --release

7. Run Synthetic Data Generators (Optional)

To synthesize demo patients and phantom previews:

python data-gen/generate_demo_patients.py
python data-gen/generate_phantomnet_demo.py

8. Run Express Backend

From the monorepo root, start the backend server and BullMQ processing worker:

pnpm --filter backend dev

9. Launch Electron Desktop GUI

Launch the Electron clinical console:

pnpm --filter electron dev

πŸ“„ License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

About

K-space native detection of neurological pathologies, including microbleeds, invisible in standard reconstructed MRI images. Learns directly from raw MRI frequency-domain data to surface findings that image-based analysis structurally misses.

Topics

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages