# bidur-khanal/spinecurvest architecture

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

- Interactive diagram: https://gitdiagram.com/bidur-khanal/spinecurvest
- Repository: https://github.com/bidur-khanal/spinecurvest

## Overview

##### Project Type and Purpose
- This repository implements an end-to-end research pipeline (not a web app) for automated spine curvature estimation and Cobb angle calculation. It combines a two-stage deep-learning approach (object detection + landmark estimation) with post-processing and MATLAB scripts to produce the final angles from spinal X-ray images.

##### File Structure Analysis
- Top-level modules:
- Object_Detection – Faster-RCNN via the Luminoth framework, configured by config.yml, with TestAllImage.py.
- Landmark_Detection – Keras/DenseNet code (model.py, train.py, test.py) plus utility routines in all_utils.py.
- CobbAngle_Calculation – MATLAB scripts (angleCal_demo.m, polyfit_lmarks.m, isS.m) and a results folder for sample outputs.
- Jupyter_Notebooks – exploratory and utility notebooks for testing and ground-truth generation.
- utils – Python helpers (compare_angles.py, smape.py) used during evaluation.
- TestAll.py – top-level Python driver that glues all stages together.
- Config/dependency files: .gitmodules (submodule for Luminoth), config.yml, LICENSE.

##### README Insights
- The pipeline has two separately trained networks:
a. Object Detector to locate each vertebra.
b. Landmark Estimator to predict four corner landmarks per vertebra.
- Post-processing includes outlier rejection and curve smoothing.
- Final step computes three Cobb angles (MT, PT, TL/L).

1. Input: Raw spinal X-ray images.
2. Object Detector Module:
- Technology: Python, Luminoth (Faster-RCNN), config.yml.
3. Landmark Detector Module:
- Technology: Python, Keras, DenseNet (Landmark_Detection).
- Input: Cropped vertebra images.
- Output: (x,y) coordinates for 4 corners per vertebra.
4. Post-processing Module:
- Outlier Rejection & Curve Smoothing.
- Technology: Python utils and/or MATLAB pre-processing.
5. Cobb Angle Calculation Module:
- Technology: MATLAB (CobbAngle_Calculation/*.m).
- Uses polyfit and slope computations.
- Output: MT, PT, TL/L angle values.
6. Evaluation & Utilities:
- Python scripts: utils/compare_angles.py, utils/smape.py.
- Jupyter Notebooks for ground truth and analysis.
7. Orchestration:
- TestAll.py drives the end-to-end flow.

- Raw Images → Object Detector → Vertebra BBoxes
- BBoxes → Landmark Detector → Landmark Coordinates
- Coordinates → Post-processing → Smoothed Landmark Curve
- Smoothed Curve → MATLAB Angle Calculator → Cobb Angles
- Cobb Angles → utils → SMAPE/Evaluation Metrics
- Jupyter Notebooks tap into intermediate outputs for visualization.

c. Architectural Patterns & Principles:
- Pipeline / Dataflow architecture: each stage transforms data.
- Modular separation: object detection, landmark estimation, post-processing, and evaluation are distinct modules.
- Reuse of specialized tools: Luminoth, Keras, MATLAB – each used for best-fit tasks.

d. Key Technologies & Frameworks:
- Python 3, Luminoth (Faster-RCNN), Keras (DenseNet), MATLAB.
- Configuration via YAML.
- Jupyter for prototyping.
- Utility scripts for metric calculation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input
    Raw["Raw X-ray Images"]:::data

    %% Object Detection Module
    subgraph "Object Detection Module"
        OD_main["Object Detector (Python + Luminoth)"]:::dl
        OD_conf["config.yml"]:::dl
        OD_testAll["TestAllImage.py"]:::dl
        lum["luminoth/"]:::dl
    end

    %% Landmark Detection Module
    subgraph "Landmark Detection Module"
        LD_main["Landmark Detector (Python + Keras)"]:::dl
        model["model.py"]:::dl
        trainLD["train.py"]:::dl
        testLD["test.py"]:::dl
        utilsLD["all_utils.py"]:::dl
    end

    %% Post-processing Module
    subgraph "Post-processing Module"
        cmp["compare_angles.py"]:::pp
        smp["smape.py"]:::pp
    end

    %% Cobb Angle Calculation Module
    subgraph "Cobb Angle Calculation Module"
        m1["angleCal_demo.m"]:::matlab
        m2["polyfit_lmarks.m"]:::matlab
        m3["isS.m"]:::matlab
        Results["results/"]:::store
    end

    %% Evaluation & Notebooks
    subgraph "Evaluation & Notebooks"
        NB1["Test_codes.ipynb"]:::eval
        NB2["generate_groundtruth.ipynb"]:::eval
    end

    %% Orchestration
    Orch["TestAll.py (Orchestration)"]:::orch

    %% Data Flow
    Raw --> OD_main
    OD_main --> LD_main
    LD_main --> cmp
    cmp --> smp
    smp --> m1
    m1 --> m2
    m1 --> m3
    m1 --> Results
    Results --> NB1
    Results --> NB2

    %% Orchestration Links
    Orch --> OD_main
    Orch --> LD_main
    Orch --> cmp
    Orch --> m1

    %% Click Events
    click OD_conf "https://github.com/bidur-khanal/spinecurvest/blob/master/Object_Detection/config.yml"
    click OD_testAll "https://github.com/bidur-khanal/spinecurvest/blob/master/Object_Detection/TestAllImage.py"
    click lum "https://github.com/bidur-khanal/spinecurvest/tree/master/Object_Detection/luminoth/"
    click OD_main "https://github.com/bidur-khanal/spinecurvest/tree/master/Object_Detection/"
    click model "https://github.com/bidur-khanal/spinecurvest/blob/master/Landmark_Detection/model.py"
    click trainLD "https://github.com/bidur-khanal/spinecurvest/blob/master/Landmark_Detection/train.py"
    click testLD "https://github.com/bidur-khanal/spinecurvest/blob/master/Landmark_Detection/test.py"
    click utilsLD "https://github.com/bidur-khanal/spinecurvest/blob/master/Landmark_Detection/all_utils.py"
    click cmp "https://github.com/bidur-khanal/spinecurvest/blob/master/utils/compare_angles.py"
    click smp "https://github.com/bidur-khanal/spinecurvest/blob/master/utils/smape.py"
    click m1 "https://github.com/bidur-khanal/spinecurvest/blob/master/CobbAngle_Calculation/angleCal_demo.m"
    click m2 "https://github.com/bidur-khanal/spinecurvest/blob/master/CobbAngle_Calculation/polyfit_lmarks.m"
    click m3 "https://github.com/bidur-khanal/spinecurvest/blob/master/CobbAngle_Calculation/isS.m"
    click Results "https://github.com/bidur-khanal/spinecurvest/tree/master/CobbAngle_Calculation/results/"
    click NB1 "https://github.com/bidur-khanal/spinecurvest/blob/master/Jupyter_Notebooks/Test_codes.ipynb"
    click NB2 "https://github.com/bidur-khanal/spinecurvest/blob/master/Jupyter_Notebooks/generate_groundtruth.ipynb"
    click Orch "https://github.com/bidur-khanal/spinecurvest/blob/master/TestAll.py"

    %% Styles
    classDef dl fill:#AED6F1,stroke:#1F618D,color:#1B2631;
    classDef pp fill:#ABEBC6,stroke:#196F3D,color:#1B2631;
    classDef matlab fill:#A9DFBF,stroke:#1D8348,color:#1B2631;
    classDef eval fill:#F5B041,stroke:#B9770E,color:#1B2631;
    classDef orch fill:#D2B4DE,stroke:#6C3483,color:#1B2631;
    classDef store fill:#F8C471,stroke:#B9770E,color:#1B2631;
    classDef data fill:#D6EAF8,stroke:#2E86C1,color:#1B2631;
```
