# andyleow/ultrasound_image_reconstruction architecture

> Architecture diagram of the GitHub repository andyleow/ultrasound_image_reconstruction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andyleow/ultrasound_image_reconstruction
- Repository: https://github.com/andyleow/ultrasound_image_reconstruction

## Overview

##### File Structure Analysis
- Top-Level Directories & Files
- src/
– cpuDAS, cpuFBF: MATLAB‐callable .m wrappers around CPU algorithms
– gpuDAS, gpuFBF: CUDA/C++ source (.cu/.cuh), mex build artifacts (.mexa64/.mexw64), and nvcc build config (xml)
- util/
– help_func: MATLAB beamforming helpers (CPU/GPU, Fourier/DAS)
– matlab-serialization-master: C++/MATLAB serialization library for data I/O
– savefast: fast MATLAB .mat writer
- examples/
– Offline: pure MATLAB demos calling mex functions
– Vantage: live scanner integration scripts
- makefile.m: top-level MATLAB build script
- README.md: usage, build instructions, requirements

##### README Insights
- Technology stack: MATLAB 2017b+, CUDA Toolkit 9.0, Visual Studio 2015 (Win) or GCC (Linux)
- Build process: mex commands invoking nvcc via xml configs
- Usage modes:
a) Offline reconstruction (batch)
b) Real-time pipeline (Vantage scanner → mex GPU kernels → MATLAB display)

a. Main Components
1. MATLAB Frontend
- User scripts & GUIs (examples/Offline & examples/Vantage)
2. MEX Gateway
- mexFunction entry points in cu*.cu / .cuh
3. CPU Beamformer Module
- DAS_CPU_Func.m, FBF_CPU_Func.m
4. GPU Beamformer Module
- cuDAS_*.cu(u), cuFBF_*.cu(u) kernels & helper functions
5. Utilities Layer
- helper MATLAB functions (util/help_func)
- serialization (util/matlab-serialization-master)
- fast save (util/savefast)
6. Hardware & External Services
- Host CPU / MATLAB runtime
- GPU device (CUDA)
- Vantage ultrasound scanner API

b. Relationships & Data Flow
1. Data Acquisition
- Offline: load raw IQ data via serialization library
- Real-time: Vantage scanner SDK streams raw data into MATLAB
2. Invocation
- MATLAB calls mex wrappers → dispatch to CPU or GPU kernels
3. Processing
- CPU: delay-and-sum or Fourier beamforming in pure MATLAB or via CPU MEX
- GPU: raw echo data transferred to GPU memory → CUDA kernels execute beamforming
4. Result
- Beamformed image passed back to MATLAB workspace → visualization
5. Persistence (offline mode)
- Optionally save results using savefast

c. Architectural Patterns & Principles
- Layered/pipeline architecture (acquisition → processing → visualization)
- Plugin-style native modules (mex functions as extension points)
- Clear host/device separation (CPU vs. GPU implementations)
- Reusable utility libraries for serialization and I/O

d. Key Technologies & Frameworks
- MATLAB mex API
- CUDA C/C++ (nvcc, xml build configs)
- Visual Studio (Windows) / GCC (Linux)
- Custom MATLAB scripts for build orchestration (makefile.m)
- Third-party serialization and fast-save libraries

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    Scanner["Vantage Scanner"]:::external
    Host["Host CPU / MATLAB Runtime"]:::external
    GPUDevice["GPU Device (CUDA)"]:::external

    %% Frontend Layer
    subgraph "MATLAB Frontend"
        OfflineCPU["CPU_DASbeamforming_main.m"]:::frontend
        CPUFBF["CPU_FBF_main_test.m"]:::frontend
        GPU_DAS_ex["GPU_DASbeamforming_main.m"]:::frontend
        GPU_FBF_ex["GPU_FourierBeamforming_main.m"]:::frontend
        V_Setup1["SetUpP4_2vFlashAngles_CUDAS.m"]:::frontend
        V_Setup2["SetupL22_14v_FlashAngleHFR_CUDASv1.m"]:::frontend
        V_Setup3["SetupL22_14v_FlashAngleHFR_CUFBFv1.m"]:::frontend
        V_Setup4["SetupMatrix1024_8FullFlashDM_HFR.m"]:::frontend
    end

    %% MEX Gateway
    subgraph "MEX Gateway"
        CPU_MEX_DAS["DAS_CPU_Func.m"]:::module
        CPU_MEX_FBF["FBF_CPU_Func.m"]:::module
        GPU_MEX_DAS["cuDAS_*.cu / .mexa*"]:::module
        GPU_MEX_FBF["cuFBF_*.cu / .mexa*"]:::module
    end

    %% Beamformer Modules
    subgraph "CPU Beamformer Module"
        CPU_MEX_DAS
        CPU_MEX_FBF
    end
    subgraph "GPU Beamformer Module"
        GPU_MEX_DAS
        GPU_MEX_FBF
    end

    %% Utilities Layer
    subgraph "Utilities"
        HelpFunc["help_func/*.m"]:::util
        Serialization["matlab-serialization-master"]:::util
        SaveFast["savefast"]:::util
    end

    %% Build & Configuration
    Makefile["makefile.m"]:::build
    Config1["nvcc9_g++.xml"]:::build
    Config2["nvcc_msvcpp2015.xml"]:::build

    %% Documentation
    README["README.md"]:::external

    %% Connections - Frontend to MEX Gateway
    OfflineCPU -->|"calls"| CPU_MEX_DAS
    CPUFBF -->|"calls"| CPU_MEX_FBF
    GPU_DAS_ex -->|"calls"| GPU_MEX_DAS
    GPU_FBF_ex -->|"calls"| GPU_MEX_FBF
    V_Setup1 -->|"real-time"| GPU_MEX_DAS
    V_Setup2 -->|"real-time"| GPU_MEX_DAS
    V_Setup3 -->|"real-time"| GPU_MEX_FBF
    V_Setup4 -->|"real-time"| GPU_MEX_FBF

    Scanner -->|"streams raw IQ data"| V_Setup1
    Scanner -->|"streams raw IQ data"| V_Setup2
    Scanner -->|"streams raw IQ data"| V_Setup3
    Scanner -->|"streams raw IQ data"| V_Setup4

    Host -->|"runtime host"| CPU_MEX_DAS
    Host -->|"runtime host"| CPU_MEX_FBF
    Host -->|"runtime host"| GPU_MEX_DAS
    Host -->|"runtime host"| GPU_MEX_FBF
    GPUDevice -->|"executes kernels"| GPU_MEX_DAS
    GPUDevice -->|"executes kernels"| GPU_MEX_FBF

    %% Utilities to Modules
    HelpFunc -->|"helper calls"| CPU_MEX_DAS
    HelpFunc -->|"helper calls"| CPU_MEX_FBF
    HelpFunc -->|"helper calls"| GPU_MEX_DAS
    HelpFunc -->|"helper calls"| GPU_MEX_FBF
    Serialization -->|"load/save data"| CPU_MEX_DAS
    Serialization -->|"load/save data"| CPU_MEX_FBF
    SaveFast -->|"save results"| CPU_MEX_DAS
    SaveFast -->|"save results"| CPU_MEX_FBF

    %% Build configs to MEX Gateway
    Makefile -->|"build orchestrator"| CPU_MEX_DAS
    Makefile -->|"build orchestrator"| CPU_MEX_FBF
    Makefile -->|"build orchestrator"| GPU_MEX_DAS
    Makefile -->|"build orchestrator"| GPU_MEX_FBF
    Config1 -->|"nvcc config"| GPU_MEX_DAS
    Config2 -->|"nvcc config"| GPU_MEX_DAS
    Config1 -->|"nvcc config"| GPU_MEX_FBF
    Config2 -->|"nvcc config"| GPU_MEX_FBF

    README -->|"documentation"| Host

    %% Click Events
    click OfflineCPU "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/examples/Offline/CPU_DASbeamforming_main.m"
    click CPUFBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/examples/Offline/CPU_FBF_main_test.m"
    click GPU_DAS_ex "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/examples/Offline/GPU_DASbeamforming_main.m"
    click GPU_FBF_ex "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/examples/Offline/GPU_FourierBeamforming_main.m"
    click V_Setup1 "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/examples/Vantage/SetUpP4_2vFlashAngles_CUDAS.m"
    click V_Setup2 "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/examples/Vantage/SetupL22_14v_FlashAngleHFR_CUDASv1.m"
    click V_Setup3 "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/examples/Vantage/SetupL22_14v_FlashAngleHFR_CUFBFv1.m"
    click V_Setup4 "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/examples/Vantage/SetupMatrix1024_8FullFlashDM_HFR.m"
    click CPU_MEX_DAS "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/cpuDAS/DAS_CPU_Func.m"
    click CPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/cpuFBF/FBF_CPU_Func.m"
    click GPU_MEX_DAS "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuDAS/cuDAS_function.cu"
    click GPU_MEX_DAS "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuDAS/cuDAS_int.cu"
    click GPU_MEX_DAS "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuDAS/cuDAS_single.cu"
    click GPU_MEX_DAS "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuDAS/cuDAS_int.mexa64"
    click GPU_MEX_DAS "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuDAS/cuDAS_single.mexa64"
    click GPU_MEX_DAS "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuDAS/cuDAS.cuh"
    click GPU_MEX_DAS "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuDAS/nvcc9_g++.xml"
    click GPU_MEX_DAS "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuDAS/nvcc_msvcpp2015.xml"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/cuFBF_main.cu"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/cuFBF_int.cu"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/cuFBF_single.cu"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/cuFBF_int.mexa64"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/cuFBF_int.mexw64"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/cuFBF_single.mexa64"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/cuFBF_single.mexw64"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/cuFBF.cuh"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/Version.txt"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/nvcc9_g++.xml"
    click GPU_MEX_FBF "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/src/gpuFBF/nvcc_msvcpp2015.xml"
    click HelpFunc "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/help_func/DAS_CPU_beamforming.m"
    click HelpFunc "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/help_func/Fourier_CPU_beamforming.m"
    click HelpFunc "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/help_func/DAS_GPU_beamforming.m"
    click HelpFunc "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/help_func/Fourier_GPU_beamforming.m"
    click HelpFunc "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/help_func/computeFIR.m"
    click HelpFunc "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/help_func/genParams.m"
    click HelpFunc "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/help_func/genTransducer.m"
    click Serialization "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/matlab-serialization-master/deserialize.m"
    click Serialization "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/matlab-serialization-master/serialize.m"
    click Serialization "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/matlab-serialization-master/deserialize.cc"
    click Serialization "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/matlab-serialization-master/serialize.cc"
    click Serialization "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/matlab-serialization-master/deserialize.mexa64"
    click Serialization "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/matlab-serialization-master/deserialize.mexw64"
    click Serialization "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/matlab-serialization-master/serialize.mexa64"
    click Serialization "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/matlab-serialization-master/serialize.mexw64"
    click Serialization "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/matlab-serialization-master/serialiseLargeEx.m"
    click SaveFast "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/savefast/savefast.m"
    click SaveFast "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/util/savefast/license.txt"
    click Makefile "https://github.com/andyleow/ultrasound_image_reconstruction/blob/master/makefile.m"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#0000FF;
    classDef module fill:#90EE90,stroke:#008000;
    classDef util fill:#FFA500,stroke:#FF8C00;
    classDef external fill:#D3D3D3,stroke:#A9A9A9;
    classDef build fill:#EEEEEE,stroke:#999999;
```
